pitrou commented on code in PR #13781: URL: https://github.com/apache/arrow/pull/13781#discussion_r949387181
########## docs/source/developers/bug_reports.rst: ########## @@ -18,82 +18,70 @@ .. _bug-reports: ******************************** -Report bugs and propose features +Bug reports and feature requests ******************************** -Using the software and sharing your experience is a very helpful contribution -itself. Those who actively develop Arrow need feedback from users on what -works and what doesn't. Alerting us to unexpected behavior and missing features, -even if you can't solve the problems yourself, help us understand and prioritize -work to improve the libraries. +Arrow relies upon user feedback to identify defects and improvement +opportunities. All users are encouraged to participate by creating bug reports +and feature request or commenting on existing issues. Even if you cannot +contribute solutions to the issues yourself, your feedback helps us understand +problems and prioritize work to improve the libraries. -We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ -to manage our development "todo" list and to maintain changelogs for releases. -In addition, the project's `Confluence site <https://cwiki.apache.org/confluence/display/ARROW>`_ -has some useful higher-level views of the JIRA issues. +.. _apache-arrow-jira: -To create a JIRA issue, you'll need to have an account on the ASF JIRA, which -you can `sign yourself up for <https://issues.apache.org/jira/secure/Signup!default.jspa>`_. -The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA -project name for Arrow is "ARROW". +Apache Arrow Jira +================= -You don't need any special permissions on JIRA to be able to create issues. -Once you are more involved in the project and want to do more on JIRA, such as -assign yourself an issue, you will need "Contributor" permissions on the -Apache Arrow JIRA. To get this role, ask on the mailing list for a project -maintainer's help. +The Arrow project uses `Jira <https://issues.apache.org/jira/projects/ARROW/issues>`_ +to track issues - both bug reports and feature requests. No account or +permissions are required to view or search Jira issues. The Jira server +hosts issue tracking for multiple Apache projects. The Jira project name for +Arrow is "ARROW". +.. _required-permissions: -.. _jira-tips: +Required permissions +++++++++++++++++++++ -Tips for using JIRA -=================== +Any registered ASF Jira account may create Jira issues in the Apache Arrow Review Comment: ```suggestion Any registered Apache Software Foundation (ASF) Jira account may create Jira issues in the Apache Arrow ``` ########## docs/source/developers/bug_reports.rst: ########## @@ -18,82 +18,70 @@ .. _bug-reports: ******************************** -Report bugs and propose features +Bug reports and feature requests ******************************** -Using the software and sharing your experience is a very helpful contribution -itself. Those who actively develop Arrow need feedback from users on what -works and what doesn't. Alerting us to unexpected behavior and missing features, -even if you can't solve the problems yourself, help us understand and prioritize -work to improve the libraries. +Arrow relies upon user feedback to identify defects and improvement +opportunities. All users are encouraged to participate by creating bug reports +and feature request or commenting on existing issues. Even if you cannot Review Comment: ```suggestion and feature requests or commenting on existing issues. Even if you cannot ``` ########## docs/source/developers/bug_reports.rst: ########## @@ -186,10 +176,109 @@ Good reproducible examples or minimal bug reports can be found in next tabs: #> 1 rows x 1 columns #> $x <timestamp[ns]> - -Other resources: +Other resources for producing useful bug reports: * `Python: Craft Minimal Bug Reports by Matthew Rocklin <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_ * `R: Tidyverse: Make a reprex <https://www.tidyverse.org/help/#reprex>`_ * `R: Tidyverse's Reprex do's and don'ts <https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html>`_ * `Mozilla's bug-reporting guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_ + +.. _identify-component: + +Identify Arrow component +++++++++++++++++++++++++ + +Arrow is an expansive project supporting many languages and organized into a +number of components. Identifying the affected component(s) helps new issues +get attention from appropriate contributors. + +* Use the **Component** field to indicate the area of the project that your + issue pertains to (for example "Python" or "C++"). +* Also prefix the issue title with the component name in brackets, for example + ``[Python] issue summary`` ; this helps when navigating lists of open issues, + and it also makes our changelogs more readable. Most prefixes are exactly the + same as the **Component** name, with the following exceptions: + + * **Component:** Continuous Integration — **Summary prefix:** [CI] + * **Component:** Developer Tools — **Summary prefix:** [Dev] + * **Component:** Documentation — **Summary prefix:** [Docs] + +.. _affected-version: + +Identify affected version ++++++++++++++++++++++++++ + +If you're reporting something that used to work in a previous version +but doesn't work in the current release, you can add the **Affects version** +field to identify the earliest known version where the bug is observed. +For feature requests and other proposals, leave **Affects version** empty as +it is not applicable. + +.. _issue-lifecycle: + +Issue lifecycle +=============== + +Both bug reports and feature requests follow a defined lifecycle. The issue +**Status** field is used to document the current state of the issue, while the +**Resolution** field indicates the outcome of issues that have reached +terminal status. + + +.. _issue-status: + +Issue Status +++++++++++++ + +The Arrow project uses the following statuses in Jira to indicate what has - +and will be - done on an issue: + +* **Open** - This is the initial issue state, prior to a contributor assigning + the issue and starting progress. Issues in this state should be unassigned. +* **In progress** - At the time a contributor self-assigns an issue, the status + should be set to In progress by clicking the **Start progress** button. All + issues in this status should have an assignee - unassigned issues will be + set back to a status of Open. Issues remain "in progress" until resolved or + closed, including during review of pull requests. +* **Resolved** - This is a terminal status indicating action has been taken + on the issue, which is now considered completed. Issues in a resolved status + may have the following resolution codes set: + + * Fixed + * Implemented + * Done + +* **Closed** - Another terminal status, Closed indicates the issue is complete, + but *without* action being taken. The following resolution codes apply to + issues in Closed status: + + * Won't Fix + * Duplicate + * Invalid + * Incomplete + * Cannot Reproduce + * Not a Problem + * Not a Bug + * Workaround + * Information Provided + * Works for Me + * Won't Do + * Abandoned + +* **Reopened** - When an issue has been closed or resolved, but additional + attention is needed, it may be reopened. + + +.. _issue-assignment: + +Issue assignment +++++++++++++++++ + +Assignment signals commitment to work on an issue, and should be self-assigned +when that work starts. At the same time the issue is assigned, the status +field should be updated. + +The Arrow project relies upon volunteer contributors, and we recognize that Review Comment: Same remark re "volunteer". ########## docs/source/developers/bug_reports.rst: ########## @@ -18,82 +18,70 @@ .. _bug-reports: ******************************** -Report bugs and propose features +Bug reports and feature requests ******************************** -Using the software and sharing your experience is a very helpful contribution -itself. Those who actively develop Arrow need feedback from users on what -works and what doesn't. Alerting us to unexpected behavior and missing features, -even if you can't solve the problems yourself, help us understand and prioritize -work to improve the libraries. +Arrow relies upon user feedback to identify defects and improvement +opportunities. All users are encouraged to participate by creating bug reports +and feature request or commenting on existing issues. Even if you cannot +contribute solutions to the issues yourself, your feedback helps us understand +problems and prioritize work to improve the libraries. -We use `JIRA <https://issues.apache.org/jira/projects/ARROW/issues>`_ -to manage our development "todo" list and to maintain changelogs for releases. -In addition, the project's `Confluence site <https://cwiki.apache.org/confluence/display/ARROW>`_ -has some useful higher-level views of the JIRA issues. +.. _apache-arrow-jira: -To create a JIRA issue, you'll need to have an account on the ASF JIRA, which -you can `sign yourself up for <https://issues.apache.org/jira/secure/Signup!default.jspa>`_. -The JIRA server hosts bugs and issues for multiple Apache projects. The JIRA -project name for Arrow is "ARROW". +Apache Arrow Jira +================= -You don't need any special permissions on JIRA to be able to create issues. -Once you are more involved in the project and want to do more on JIRA, such as -assign yourself an issue, you will need "Contributor" permissions on the -Apache Arrow JIRA. To get this role, ask on the mailing list for a project -maintainer's help. +The Arrow project uses `Jira <https://issues.apache.org/jira/projects/ARROW/issues>`_ +to track issues - both bug reports and feature requests. No account or +permissions are required to view or search Jira issues. The Jira server +hosts issue tracking for multiple Apache projects. The Jira project name for +Arrow is "ARROW". +.. _required-permissions: -.. _jira-tips: +Required permissions +++++++++++++++++++++ -Tips for using JIRA -=================== +Any registered ASF Jira account may create Jira issues in the Apache Arrow +project without additional permissions. Individuals may +`create an ASF Jira account here <https://issues.apache.org/jira/secure/Signup!default.jspa>`_. +Self-assigning issues to work requires +the "Contributor" permission. This permission is set by project maintainers, +and may be requested by emailing the :ref:`development mailing list <mailing_list>`. -Before you create a new issue, we recommend you first -`search <https://issues.apache.org/jira/issues/?jql=project%20%3D%20ARROW%20AND%20resolution%20%3D%20Unresolved>`_ -among existing Arrow issues. +.. _creating-issues: -When reporting a new issue, follow these conventions to help make sure the -right people see it: +Creating issues +=============== -* Use the **Component** field to indicate the area of the project that your - issue pertains to (for example "Python" or "C++"). -* Also prefix the issue title with the component name in brackets, for example - ``[Python] issue name`` ; this helps when navigating lists of open issues, - and it also makes our changelogs more readable. Most prefixes are exactly the - same as the **Component** name, with the following exceptions: +No one likes having bugs or feature gaps in their software, and in an ideal +world, all bugs would get fixed as soon as they were reported. However, time +and attention are finite, especially in an open-source project where most +contributors are participating in their spare time. All contributors in Apache +projects are volunteers and act as individuals, even if they are contributing Review Comment: Unless we have a different meaning of "volunteers", Arrow contributors are certainly not all volunteers. Many of them are paid for it. ########## docs/source/developers/bug_reports.rst: ########## @@ -186,10 +176,109 @@ Good reproducible examples or minimal bug reports can be found in next tabs: #> 1 rows x 1 columns #> $x <timestamp[ns]> - -Other resources: +Other resources for producing useful bug reports: * `Python: Craft Minimal Bug Reports by Matthew Rocklin <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_ * `R: Tidyverse: Make a reprex <https://www.tidyverse.org/help/#reprex>`_ * `R: Tidyverse's Reprex do's and don'ts <https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html>`_ * `Mozilla's bug-reporting guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_ + +.. _identify-component: + +Identify Arrow component +++++++++++++++++++++++++ + +Arrow is an expansive project supporting many languages and organized into a +number of components. Identifying the affected component(s) helps new issues +get attention from appropriate contributors. + +* Use the **Component** field to indicate the area of the project that your + issue pertains to (for example "Python" or "C++"). +* Also prefix the issue title with the component name in brackets, for example + ``[Python] issue summary`` ; this helps when navigating lists of open issues, + and it also makes our changelogs more readable. Most prefixes are exactly the + same as the **Component** name, with the following exceptions: + + * **Component:** Continuous Integration — **Summary prefix:** [CI] + * **Component:** Developer Tools — **Summary prefix:** [Dev] + * **Component:** Documentation — **Summary prefix:** [Docs] + +.. _affected-version: + +Identify affected version ++++++++++++++++++++++++++ + +If you're reporting something that used to work in a previous version +but doesn't work in the current release, you can add the **Affects version** +field to identify the earliest known version where the bug is observed. +For feature requests and other proposals, leave **Affects version** empty as +it is not applicable. + +.. _issue-lifecycle: + +Issue lifecycle +=============== + +Both bug reports and feature requests follow a defined lifecycle. The issue +**Status** field is used to document the current state of the issue, while the +**Resolution** field indicates the outcome of issues that have reached +terminal status. + + +.. _issue-status: + +Issue Status +++++++++++++ + +The Arrow project uses the following statuses in Jira to indicate what has - +and will be - done on an issue: + +* **Open** - This is the initial issue state, prior to a contributor assigning + the issue and starting progress. Issues in this state should be unassigned. +* **In progress** - At the time a contributor self-assigns an issue, the status + should be set to In progress by clicking the **Start progress** button. All + issues in this status should have an assignee - unassigned issues will be + set back to a status of Open. Issues remain "in progress" until resolved or + closed, including during review of pull requests. +* **Resolved** - This is a terminal status indicating action has been taken + on the issue, which is now considered completed. Issues in a resolved status + may have the following resolution codes set: Review Comment: We should really always use "Fixed" for consistency, IMHO. ########## docs/source/developers/bug_reports.rst: ########## @@ -186,10 +176,109 @@ Good reproducible examples or minimal bug reports can be found in next tabs: #> 1 rows x 1 columns #> $x <timestamp[ns]> - -Other resources: +Other resources for producing useful bug reports: * `Python: Craft Minimal Bug Reports by Matthew Rocklin <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_ * `R: Tidyverse: Make a reprex <https://www.tidyverse.org/help/#reprex>`_ * `R: Tidyverse's Reprex do's and don'ts <https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html>`_ * `Mozilla's bug-reporting guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_ + +.. _identify-component: + +Identify Arrow component +++++++++++++++++++++++++ + +Arrow is an expansive project supporting many languages and organized into a +number of components. Identifying the affected component(s) helps new issues +get attention from appropriate contributors. + +* Use the **Component** field to indicate the area of the project that your + issue pertains to (for example "Python" or "C++"). +* Also prefix the issue title with the component name in brackets, for example + ``[Python] issue summary`` ; this helps when navigating lists of open issues, + and it also makes our changelogs more readable. Most prefixes are exactly the + same as the **Component** name, with the following exceptions: + + * **Component:** Continuous Integration — **Summary prefix:** [CI] + * **Component:** Developer Tools — **Summary prefix:** [Dev] + * **Component:** Documentation — **Summary prefix:** [Docs] + +.. _affected-version: + +Identify affected version ++++++++++++++++++++++++++ + +If you're reporting something that used to work in a previous version +but doesn't work in the current release, you can add the **Affects version** +field to identify the earliest known version where the bug is observed. +For feature requests and other proposals, leave **Affects version** empty as +it is not applicable. + +.. _issue-lifecycle: + +Issue lifecycle +=============== + +Both bug reports and feature requests follow a defined lifecycle. The issue +**Status** field is used to document the current state of the issue, while the +**Resolution** field indicates the outcome of issues that have reached +terminal status. + + +.. _issue-status: + +Issue Status +++++++++++++ + +The Arrow project uses the following statuses in Jira to indicate what has - +and will be - done on an issue: + +* **Open** - This is the initial issue state, prior to a contributor assigning + the issue and starting progress. Issues in this state should be unassigned. +* **In progress** - At the time a contributor self-assigns an issue, the status + should be set to In progress by clicking the **Start progress** button. All + issues in this status should have an assignee - unassigned issues will be + set back to a status of Open. Issues remain "in progress" until resolved or + closed, including during review of pull requests. +* **Resolved** - This is a terminal status indicating action has been taken + on the issue, which is now considered completed. Issues in a resolved status + may have the following resolution codes set: + + * Fixed + * Implemented + * Done + +* **Closed** - Another terminal status, Closed indicates the issue is complete, + but *without* action being taken. The following resolution codes apply to + issues in Closed status: + + * Won't Fix + * Duplicate + * Invalid + * Incomplete + * Cannot Reproduce + * Not a Problem + * Not a Bug + * Workaround + * Information Provided + * Works for Me + * Won't Do + * Abandoned + +* **Reopened** - When an issue has been closed or resolved, but additional + attention is needed, it may be reopened. + + +.. _issue-assignment: + +Issue assignment +++++++++++++++++ + +Assignment signals commitment to work on an issue, and should be self-assigned Review Comment: "Assignment ... should be self-assigned" doesn't look grammatically sound? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
