You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d53bce2
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
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.
29
29
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:
34
31
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
+
=================
39
34
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".
45
40
41
+
.. _required-permissions:
46
42
47
-
.. _jira-tips:
43
+
Required permissions
44
+
++++++++++++++++++++
48
45
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>`_.
51
50
52
-
Before you create a new issue, we recommend you first
for unresolved existing issues identifying the same problem or feature request.
81
70
82
-
Tips for successful bug reports
83
-
================================
71
+
.. _describe-issue:
84
72
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
+
+++++++++++++++++
91
75
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:
97
79
98
80
* **Clear, minimal steps to reproduce the issue, with as few non-Arrow
99
81
dependencies as possible.** If there's a problem on reading a file, try to
@@ -103,13 +85,15 @@ to the best of your ability,**
103
85
* Any relevant operating system, language, and library version information
104
86
* If it isn't obvious, clearly state the expected behavior and what actually
105
87
happened.
88
+
* Avoid overloading a single issue with multiple problems or feature requests.
89
+
Each issue should deal with a single bug or feature.
106
90
107
91
If a developer can't get a failing unit test, they won't be able to know that
108
92
the issue has been identified, and they won't know when it has been fixed.
109
93
Try to anticipate the questions you might be asked by someone working to
110
94
understand the issue and provide those supporting details up front.
111
95
112
-
Good reproducible examples or minimal bug reports can be found in next tabs:
96
+
Examples of good bug reports are found below:
113
97
114
98
.. tab-set::
115
99
@@ -186,10 +170,104 @@ Good reproducible examples or minimal bug reports can be found in next tabs:
186
170
#> 1 rows x 1 columns
187
171
#> $x <timestamp[ns]>
188
172
189
-
190
-
Other resources:
173
+
Other resources for producing useful bug reports:
191
174
192
175
* `Python: Craft Minimal Bug Reports by Matthew Rocklin <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_
193
176
* `R: Tidyverse: Make a reprex <https://www.tidyverse.org/help/#reprex>`_
194
177
* `R: Tidyverse's Reprex do's and don'ts <https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html>`_
0 commit comments