Skip to content

Commit d53bce2

Browse files
authored
ARROW-17322: [Docs] Documenting issue lifecycle for bugs and feature requests (#13781)
These changes aim to document the issue lifecycle - how to create new issues (largely already existed) as well as how to engage with and understand issue state later on. This also serves to document proposed processes: 1. Assigned issues idle more than 90 days may be unassigned (discussed and approved on ML) 2. Unassigned issues in "In Progress" status should be set to "Open" 3. Establishing consistent usage of Status and Resolution fields. Authored-by: Todd Farmer <[email protected]> Signed-off-by: Antoine Pitrou <[email protected]>
1 parent c90d07f commit d53bce2

4 files changed

Lines changed: 147 additions & 71 deletions

File tree

‎docs/source/developers/bug_reports.rst‎

Lines changed: 140 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -18,82 +18,64 @@
1818
.. _bug-reports:
1919

2020
********************************
21-
Report bugs and propose features
21+
Bug reports and feature requests
2222
********************************
2323

24-
Using the software and sharing your experience is a very helpful contribution
25-
itself. Those who actively develop Arrow need feedback from users on what
26-
works and what doesn't. Alerting us to unexpected behavior and missing features,
27-
even if you can't solve the problems yourself, help us understand and prioritize
28-
work to improve the libraries.
24+
Arrow relies upon user feedback to identify defects and improvement
25+
opportunities. All users are encouraged to participate by creating bug reports
26+
and feature requests or commenting on existing issues. Even if you cannot
27+
contribute solutions to the issues yourself, your feedback helps us understand
28+
problems and prioritize work to improve the libraries.
2929

30-
We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_
31-
to manage our development "todo" list and to maintain changelogs for releases.
32-
In addition, the project's `Confluence site <https://cwiki.apache.org/confluence/display/ARROW>`_
33-
has some useful higher-level views of the JIRA issues.
30+
.. _apache-arrow-jira:
3431

35-
To create a JIRA issue, you'll need to have an account on the ASF JIRA, which
36-
you can `sign yourself up for <https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
37-
The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA
38-
project name for Arrow is "ARROW".
32+
Apache Arrow Jira
33+
=================
3934

40-
You don't need any special permissions on JIRA to be able to create issues.
41-
Once you are more involved in the project and want to do more on JIRA, such as
42-
assign yourself an issue, you will need "Contributor" permissions on the
43-
Apache Arrow JIRA. To get this role, ask on the mailing list for a project
44-
maintainer's help.
35+
The Arrow project uses `Jira <https://issues.apache.org/jira/projects/ARROW/issues>`_
36+
to track issues - both bug reports and feature requests. No account or
37+
permissions are required to view or search Jira issues. The Jira server
38+
hosts issue tracking for multiple Apache projects. The Jira project name for
39+
Arrow is "ARROW".
4540

41+
.. _required-permissions:
4642

47-
.. _jira-tips:
43+
Required permissions
44+
++++++++++++++++++++
4845

49-
Tips for using JIRA
50-
===================
46+
Any registered Apache Software Foundation (ASF) Jira account may create or
47+
assign Jira issues in the Apache Arrow project without additional permissions.
48+
Individuals may
49+
`create an ASF Jira account here <https://issues.apache.org/jira/secure/Signup!default.jspa>`_.
5150

52-
Before you create a new issue, we recommend you first
53-
`search <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
54-
among existing Arrow issues.
51+
.. _creating-issues:
5552

56-
When reporting a new issue, follow these conventions to help make sure the
57-
right people see it:
53+
Creating issues
54+
===============
5855

59-
* Use the **Component** field to indicate the area of the project that your
60-
issue pertains to (for example "Python" or "C++").
61-
* Also prefix the issue title with the component name in brackets, for example
62-
``[Python] issue name`` ; this helps when navigating lists of open issues,
63-
and it also makes our changelogs more readable. Most prefixes are exactly the
64-
same as the **Component** name, with the following exceptions:
56+
Apache Arrow relies upon community contributions to address reported bugs and
57+
feature requests. As with most software projects, contributor time and
58+
resources are finite. The following guidelines aim to produce high-quality
59+
bug reports and feature requests, enabling community contributors to respond
60+
to more issues, faster:
6561

66-
* **Component:** Continuous Integration — **Summary prefix:** [CI]
67-
* **Component:** Developer Tools — **Summary prefix:** [Dev]
68-
* **Component:** Documentation — **Summary prefix:** [Docs]
62+
.. _check-existing-issues:
6963

70-
* If you're reporting something that used to work in a previous version
71-
but doesn't work in the current release, you can add the "Affects version"
72-
field. For feature requests and other proposals, "Affects version" isn't
73-
appropriate.
64+
Check existing issues
65+
+++++++++++++++++++++
7466

75-
Project maintainers may later tweak formatting and labels to help improve their
76-
visibility. They may add a "Fix version" to indicate that they're considering
77-
it for inclusion in the next release, though adding that tag is not a
78-
commitment that it will be done in the next release.
79-
80-
.. _bug-report-tips:
67+
Before you create a new issue, we recommend you first
68+
`search <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_
69+
for unresolved existing issues identifying the same problem or feature request.
8170

82-
Tips for successful bug reports
83-
================================
71+
.. _describe-issue:
8472

85-
No one likes having bugs in their software, and in an ideal world, all bugs
86-
would get fixed as soon as they were reported. However, time and attention are
87-
finite, especially in an open-source project where most contributors are
88-
participating in their spare time. All contributors in Apache projects are
89-
volunteers and act as individuals, even if they are contributing to the project
90-
as part of their job responsibilities.
73+
Issue description
74+
+++++++++++++++++
9175

92-
In order for your bug to get prompt
93-
attention, there are things you can do to make it easier for contributors to
94-
reproduce and fix it.
95-
**When you're reporting a bug, please help us understand the issue by providing,
96-
to the best of your ability,**
76+
A clear description of the problem or requested feature is the most important
77+
element of any issue. An effective description helps developers understand
78+
and efficiently engage on reported issues, and may include the following:
9779

9880
* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
9981
dependencies as possible.** If there's a problem on reading a file, try to
@@ -103,13 +85,15 @@ to the best of your ability,**
10385
* Any relevant operating system, language, and library version information
10486
* If it isn't obvious, clearly state the expected behavior and what actually
10587
happened.
88+
* Avoid overloading a single issue with multiple problems or feature requests.
89+
Each issue should deal with a single bug or feature.
10690

10791
If a developer can't get a failing unit test, they won't be able to know that
10892
the issue has been identified, and they won't know when it has been fixed.
10993
Try to anticipate the questions you might be asked by someone working to
11094
understand the issue and provide those supporting details up front.
11195

112-
Good reproducible examples or minimal bug reports can be found in next tabs:
96+
Examples of good bug reports are found below:
11397

11498
.. tab-set::
11599

@@ -186,10 +170,104 @@ Good reproducible examples or minimal bug reports can be found in next tabs:
186170
#> 1 rows x 1 columns
187171
#> $x <timestamp[ns]>
188172
189-
190-
Other resources:
173+
Other resources for producing useful bug reports:
191174

192175
* `Python: Craft Minimal Bug Reports by Matthew Rocklin <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_
193176
* `R: Tidyverse: Make a reprex <https://www.tidyverse.org/help/#reprex>`_
194177
* `R: Tidyverse's Reprex do's and don'ts <https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html>`_
195178
* `Mozilla's bug-reporting guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_
179+
180+
.. _identify-component:
181+
182+
Identify Arrow component
183+
++++++++++++++++++++++++
184+
185+
Arrow is an expansive project supporting many languages and organized into a
186+
number of components. Identifying the affected component(s) helps new issues
187+
get attention from appropriate contributors.
188+
189+
* Use the **Component** field to indicate the area of the project that your
190+
issue pertains to (for example "Python" or "C++").
191+
* Also prefix the issue title with the component name in brackets, for example
192+
``[Python] issue summary`` ; this helps when navigating lists of open issues,
193+
and it also makes our changelogs more readable. Most prefixes are exactly the
194+
same as the **Component** name, with the following exceptions:
195+
196+
* **Component:** Continuous Integration — **Summary prefix:** [CI]
197+
* **Component:** Developer Tools — **Summary prefix:** [Dev]
198+
* **Component:** Documentation — **Summary prefix:** [Docs]
199+
200+
.. _affected-version:
201+
202+
Identify affected version
203+
+++++++++++++++++++++++++
204+
205+
If you're reporting something that used to work in a previous version
206+
but doesn't work in the current release, you can add the **Affects version**
207+
field to identify the earliest known version where the bug is observed.
208+
For feature requests and other proposals, leave **Affects version** empty as
209+
it is not applicable.
210+
211+
.. _issue-lifecycle:
212+
213+
Issue lifecycle
214+
===============
215+
216+
Both bug reports and feature requests follow a defined lifecycle. The issue
217+
**Status** field is used to document the current state of the issue, while the
218+
**Resolution** field indicates the outcome of issues that have reached
219+
terminal status.
220+
221+
222+
.. _issue-status:
223+
224+
Issue Status
225+
++++++++++++
226+
227+
The Arrow project uses the following statuses in Jira to indicate what has -
228+
and will be - done on an issue:
229+
230+
* **Open** - This is the initial issue state, prior to a contributor assigning
231+
the issue and starting progress. Issues in this state should be unassigned.
232+
* **In progress** - At the time a contributor self-assigns an issue, the status
233+
should be set to In progress by clicking the **Start progress** button. All
234+
issues in this status should have an assignee - unassigned issues will be
235+
set back to a status of Open. Issues remain "in progress" until resolved or
236+
closed, including during review of pull requests.
237+
* **Resolved** - This is a terminal status indicating action has been taken
238+
on the issue, which is now considered completed. Issues in a resolved status
239+
should have a resolution code set to **Fixed**.
240+
* **Closed** - Another terminal status, Closed indicates the issue is complete,
241+
but *without* action being taken. The following resolution codes apply to
242+
issues in Closed status:
243+
244+
* Won't Fix
245+
* Duplicate
246+
* Invalid
247+
* Incomplete
248+
* Cannot Reproduce
249+
* Not a Problem
250+
* Not a Bug
251+
* Workaround
252+
* Information Provided
253+
* Works for Me
254+
* Won't Do
255+
* Abandoned
256+
257+
* **Reopened** - When an issue has been closed or resolved, but additional
258+
attention is needed, it may be reopened.
259+
260+
261+
.. _issue-assignment:
262+
263+
Issue assignment
264+
++++++++++++++++
265+
266+
Assignment signals commitment to work on an issue, and contributors should
267+
self-assign issues when that work starts. At the same time the issue is
268+
assigned, the status field should be updated to **In Progress**.
269+
270+
The Arrow project relies upon community contributors to resolve issues. We
271+
recognize that priorities and plans may change, resulting in an issue assigned
272+
to an individual who cannot attend to it. Assigned issues without updates in
273+
the past 90 days will be unassigned and set to **Open** status.

‎docs/source/developers/guide/communication.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ might think is not a good idea.
7878
.. seealso::
7979

8080
- :ref:`create_jira`
81-
- :ref:`jira-tips` and :ref:`bug-report-tips`
81+
- :ref:`creating-issues` and :ref:`bug-report-tips`
8282

8383
- If you want to **solve an issue that is already in JIRA**, you should
8484
connect with other contributors in the issue comments.

‎docs/source/developers/guide/step_by_step/finding_issues.rst‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -80,16 +80,14 @@ If you are already in JIRA dashboard click the red ``create`` button in
8080
the top to do the same.
8181

8282
You are ready to create the issue! Add a title and a description following
83-
the :ref:`tips for using JIRA <jira-tips>` and you are ready to go!
83+
the guidance in :ref:`creating issues <creating-issues>` and you are ready to go!
8484

8585
.. seealso::
86-
:ref:`Tips for using JIRA <jira-tips>`
86+
:ref:`Creating issues <creating-issues>`
8787

88-
You don’t need any special permissions on JIRA to be able to create issues.
89-
Once you are more involved in the project and want to do more on JIRA, for
90-
example assigning yourself an issue, you will need **“Contributor” permissions**.
91-
To get this role, ask on the :ref:`mailing_list` or in the comment of the JIRA
92-
issue you created.
88+
You don’t need any special permissions on JIRA to be able to create
89+
or self-assign issues.
90+
To get this role, ask on the :ref:`dev mailing list <mailing_list>`.
9391

9492
When the ticket is created you can start a discussion about it in the
9593
JIRA comments section.

0 commit comments

Comments
 (0)