http://hg.python.org/devguide/rev/252e2aabc87a changeset: 503:252e2aabc87a user: Ezio Melotti <ezio.melotti@gmail.com> date: Sun Apr 29 08:37:40 2012 +0300 summary: #119: reorganize the tracker documentation in the devguide. files: devrole.rst | 24 ---- helptriage.rst | 63 ----------- index.rst | 8 +- languishing.rst | 26 ---- tracker.rst | 197 ++++++++++++++++++++++++++++++++++++ triaging.rst | 7 - 6 files changed, 199 insertions(+), 126 deletions(-) diff --git a/devrole.rst b/devrole.rst deleted file mode 100644 --- a/devrole.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _devrole: - -Gaining the "Developer" Role on the Issue Tracker -================================================= - -When you have consistently shown the ability to properly -:ref:`help triage issues <helptriage>` without guidance, you may request that you -be given the "Developer" role on the `issue tracker`_. You can make the request -of any person who already has the Developer role. If they decide you are ready -to gain the extra privileges on the tracker they will then act as a mentor to -you until you are ready to do things entirely on your own. There is no set rule -as to how many issues you need to have helped with before or how long you have -been participating. The key requirements are that you show the desire to -help, you are able to work well with others (especially those already with the -Developer role), and that have a firm grasp of how to do things on the issue -tracker properly on your own. - -Gaining the Developer role will allow you to set any value on any issue in the -tracker, releasing you from the burden of having to ask others to set values on -an issue for you in order to properly triage something. This will not only help -speed up and simplify your work in helping out, but also help lessen the -workload for everyone by gaining your help. - -.. _issue tracker: http://bugs.python.org diff --git a/helptriage.rst b/helptriage.rst deleted file mode 100644 --- a/helptriage.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _helptriage: - -Helping Triage Issues -===================== - -Once you know your way around how Python's source files are -structured and you are comfortable working with patches, a great way to -participate is to help triage issues. Do realize, though, that experience -working on Python is needed in order to effectively help triage. - -Around the clock, new issues are being opened on the `issue tracker`_ and -existing issues are being updated. Every -issue needs to be triaged to make sure various things are in proper order. Even -without special privileges you can help with this process. - - -Bugs ----- - -For bugs, an issue needs to: - -* clearly explain the bug so it can be reproduced -* include all relevant platform details -* state what version(s) of Python are affected by the bug. - -These are things you can help with once you have experience developing for -Python. For instance, if a bug is not clearly explained enough for you to -reproduce it then there is a good chance a core developer won't be able to -either. And it is always helpful to know if a bug not only affects the -in-development version of Python, but whether it also affects other versions in -maintenance mode. And if the bug lacks a unit test that should end up in -Python's test suite, having that written can be very helpful. - -This is all helpful as it allows triagers (i.e., -:ref:`people with the Developer role on the issue tracker <devrole>`) to -properly classify an issue so it can be handled by the right core developers in -a timely fashion. - - -Patches -------- - -If an issue has a patch attached that has not been reviewed, you can help by -making sure the patch: - -* follows the style guides -* applies cleanly to an up-to-date checkout -* is a good solution to the problem it is trying to solve -* includes proper tests -* includes proper documentation changes -* submitter is listed in ``Misc/ACKS``, either already or the patch adds them - -Doing all of this allows core developers and :ref:`triagers <devrole>` to more -quickly look for subtle issues that only people with extensive experience -working on Python's code base will notice. - -There is a complete list of `open issues with patches`_ as well as a list of -`issues needing a review`_, although make sure -that someone has not already done the checklist above as it is possible the -issue is still open for reasons other than needing help being triaged. - - -.. _issue tracker: http://bugs.python.org -.. _issues needing a review: http://bugs.python.org/issue?status=1&@sort=-activity&@columns=id,activity,title,creator,status&@dispname=Show%20Needing%20Review&@startwith=0&@group=priority&@filter=&keywords=8&@action=search&@pagesize=50 -.. _open issues with patches: http://bugs.python.org/issue?status=1&@sort=-activity&@columns=id,activity,title,creator,status&@dispname=Issues%20with%20patch&@startwith=0&@group=priority&@filter=&keywords=2&@action=search&@pagesize=50 diff --git a/index.rst b/index.rst --- a/index.rst +++ b/index.rst @@ -13,10 +13,8 @@ documenting silencewarnings fixingissues - helptriage - devrole + tracker triaging - languishing communication coredev developers @@ -89,10 +87,8 @@ * :doc:`silencewarnings` * Fixing issues found by the :doc:`buildbots <buildbots>` * :doc:`fixingissues` - * :doc:`helptriage` -* :doc:`devrole` +* :ref:`tracker` and :ref:`helptriage` * :doc:`triaging` - * :doc:`languishing` * :doc:`communication` * :doc:`coredev` * :doc:`committing` diff --git a/languishing.rst b/languishing.rst deleted file mode 100644 --- a/languishing.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _languishing: - -Marking Issues as "Languishing" -=============================== - -Sometimes an issue has no clear answer. It can be because core developers -cannot agree on the proper solution (or if a problem even exists). Other -times a solution is agreed upon but writing the code for the solution would -take too much effort for little gain, and so no one wants to do the work (or -would simply break too much pre-existing code without a different solution). - -In these cases an issue will languish_ in the `issue tracker`_, and its -status should be set as such. This -serves the purpose of preventing people who are trying to :ref:`fix issues -<fixingissues>` from wasting time on issues that even core developers cannot -come up with an agreed-upon solution for. - -A good way to tell if an issue is languishing is based on whether it had -an in-depth discussion that stalled several months ago. In that instance it is -typically safe to set the status of the issue to "languishing". If you are -unsure you can always leave a comment on the issue asking if others agree that -it is languishing. - - -.. _issue tracker: http://bugs.python.org -.. _languish: http://bugs.python.org/issue?@columns=title,id,activity,status&@sort=activity&@group=priority&@filter=status&@pagesize=50&@startwith=0&status=4&@dispname=Languishing diff --git a/tracker.rst b/tracker.rst new file mode 100644 --- /dev/null +++ b/tracker.rst @@ -0,0 +1,197 @@ +.. _tracker: + +Using the Issue Tracker +======================= + +If you think you found a bug in Python, you can report it to the +`issue tracker`_. Documentation bugs can also be reported there. +Issues about the tracker should be reported to the `meta tracker`_. + + +Checking if a bug already exists +-------------------------------- + +The first step in filing a report is to determine whether the problem has +already been reported. The advantage in doing so, aside from saving the +developers time, is that you learn what has been done to fix it; it may be that +the problem has already been fixed for the next release, or additional +information is needed (in which case you are welcome to provide it if you can!). + +To do this, search the bug database using the search box on the top of the page. +An `advanced search`_ is also available by clicking on "Search" in +the sidebar. + + +Reporting an issue +------------------ + +If the problem you're reporting is not already in the `issue tracker`_, you +need to log in by entering your user and password in the form on the left. +If you don't already have a tracker account, select the "Register" link or, +if you use OpenID, one of the OpenID provider logos in the sidebar. + +It is not possible to submit a bug report anonymously. + +Being now logged in, you can submit a bug by clicking on the "Create New" link +in the sidebar. + +The submission form has a number of fields, and they are described in detail +in the :ref:`triaging` page. This is a short summary: + +* in the **Title** field, enter a *very* short description of the problem; + less than ten words is good; +* in the **Type** field, select the type of your problem (usually behavior); +* if you know which **Components** and **Versions** are affected by the issue, + you can select these too; +* if you have JavaScript enabled, you can use the **Nosy List** field to search + developers that can help with the issue by entering the name of the affected + module, operating system, or interest area. +* least but not last, you have to describe the problem in detail, including + what you expected to happen and what did happen, in the **Comment** field. + Be sure to include whether any extension modules were involved, and what + hardware and software platform you were using (including version information + as appropriate). + +The triaging team will take care of setting other fields, and possibly assign +the issue to a specific developer. You will automatically receive an update +each time an action is taken on the bug. + + +.. _helptriage: + +Helping Triage Issues +===================== + +Once you know your way around how Python's source files are +structured and you are comfortable working with patches, a great way to +participate is to help triage issues. Do realize, though, that experience +working on Python is needed in order to effectively help triage. + +Around the clock, new issues are being opened on the `issue tracker`_ and +existing issues are being updated. Every +issue needs to be triaged to make sure various things are in proper order. Even +without special privileges you can help with this process. + + +Classifying Reports +------------------- + +For bugs, an issue needs to: + +* clearly explain the bug so it can be reproduced +* include all relevant platform details +* state what version(s) of Python are affected by the bug. + +These are things you can help with once you have experience developing for +Python. For instance, if a bug is not clearly explained enough for you to +reproduce it then there is a good chance a core developer won't be able to +either. And it is always helpful to know if a bug not only affects the +in-development version of Python, but whether it also affects other versions in +maintenance mode. And if the bug lacks a unit test that should end up in +Python's test suite, having that written can be very helpful. + +This is all helpful as it allows triagers (i.e., +:ref:`people with the Developer role on the issue tracker <devrole>`) to +properly classify an issue so it can be handled by the right core developers in +a timely fashion. + + +Reviewing Patches +----------------- + +If an issue has a patch attached that has not been reviewed, you can help by +making sure the patch: + +* follows the style guides +* applies cleanly to an up-to-date clone +* is a good solution to the problem it is trying to solve +* includes proper tests +* includes proper documentation changes +* submitter is listed in ``Misc/ACKS``, either already or the patch adds them + +Doing all of this allows core developers and :ref:`triagers <devrole>` to more +quickly look for subtle issues that only people with extensive experience +working on Python's code base will notice. + + +Finding an Issue You Can Help With +---------------------------------- + +If you want to help triaging issues, you might also want to search for issues +that you are knowledgeable about. An easy way to do it, is to search for +the name of a module you are familiar with. You can also use the +`advanced search`_ and search for specific components (e.g. "Windows" if you +are a Windows developer, "Extension Modules" if you are familiar with C, etc.). +Finally you can use the "Random issue" link in the sidebar to pick random +issues until you find an issue that you like. Is not so uncommon to find old +issues that can be closed, either because they are no longer valid, or +because they have a patch that is ready to be committed, but no one had +time to do it yet. + +In the sidebar you can also find links to summaries for easy issues and +issues with a patch. + + +.. _devrole: + +Gaining the "Developer" Role on the Issue Tracker +------------------------------------------------- + +When you have consistently shown the ability to properly +help triage issues without guidance, you may request that you +be given the "Developer" role on the `issue tracker`_. You can make the request +of any person who already has the Developer role. If they decide you are ready +to gain the extra privileges on the tracker they will then act as a mentor to +you until you are ready to do things entirely on your own. There is no set rule +as to how many issues you need to have helped with before or how long you have +been participating. The key requirements are that you show the desire to +help, you are able to work well with others (especially those already with the +Developer role), and that have a firm grasp of how to do things on the issue +tracker properly on your own. + +Gaining the Developer role will allow you to set any value on any issue in the +tracker, releasing you from the burden of having to ask others to set values on +an issue for you in order to properly triage something. This will not only help +speed up and simplify your work in helping out, but also help lessen the +workload for everyone by gaining your help. + + +The Meta Tracker +================ + +If you find an issue with the `issue tracker`_, you can report it to the +`meta tracker`_. The meta tracker is where you file issues against anything +you come across when working with the issue tracker itself (e.g you can't +attach a file, the layout is broken on your browser, Rietveld gave you an +error, etc.). + +If you want to contribute to the tracker you can get a checkout of the source +and install a local instance where to experiment. You can find detailed +instructions on the `Tracker Development`_ page. + + +.. seealso:: + + `The Python issue tracker <http://bugs.python.org/>`_ + Where to report issues about Python. + + `The New-bugs-announce mailing list <http://mail.python.org/mailman/listinfo/new-bugs-announce>`_ + Where all the new issues created on the tracker are reported. + + `The Python-bugs-list mailing list <http://mail.python.org/mailman/listinfo/python-bugs-list>`_ + Where all the changes to issues are reported. + + `The meta tracker <http://psf.upfronthosting.co.za/roundup/meta/>`_ + Where to report issues about the tracker itself. + + `The Tracker development wiki page <http://wiki.python.org/moin/TrackerDevelopment>`_ + Instructions about setting up a local instance of the bug tracker. + + `The Tracker-discuss mailing list <http://mail.python.org/mailman/listinfo/tracker-discuss>`_ + Discussions about the bug tracker. + + +.. _issue tracker: http://bugs.python.org/ +.. _meta tracker: http://psf.upfronthosting.co.za/roundup/meta/ +.. _advanced search: http://bugs.python.org/issue?@template=search +.. _Tracker Development: http://wiki.python.org/moin/TrackerDevelopment diff --git a/triaging.rst b/triaging.rst --- a/triaging.rst +++ b/triaging.rst @@ -289,13 +289,6 @@ the Devguide, this page, and this section respectively. -Reporting Issues About the Tracker ----------------------------------- -The `meta tracker`_ is the tracker about the issue tracker. It is where you -file issues against anything you come across when working with the issue -tracker itself. - - .. _Doc: http://hg.python.org/cpython/file/default/Doc/ .. _Grammar: http://hg.python.org/cpython/file/default/Grammar/ .. _Lib: http://hg.python.org/cpython/file/default/Lib/ @@ -326,4 +319,3 @@ .. _Developer's guide: http://hg.python.org/devguide/ .. _GSoC: http://code.google.com/soc/ .. _issue tracker: http://bugs.python.org -.. _meta tracker: http://psf.upfronthosting.co.za/roundup/meta/ -- Repository URL: http://hg.python.org/devguide