diff --git a/pep-0003.txt b/pep-0003.txt index 5be160ab1..a1dbda4a8 100644 --- a/pep-0003.txt +++ b/pep-0003.txt @@ -1,257 +1,64 @@ PEP: 3 -Title: Guidelines for Handling Tracker Issues +Title: Guidelines for Handling Bug Reports Version: $Revision$ Last-Modified: $Date$ -Author: jeremy@alum.mit.edu (Jeremy Hylton), ncoghlan@gmail.com (Nick Coghlan) +Author: jeremy@alum.mit.edu (Jeremy Hylton) Status: Active Type: Process -Content-Type: text/x-rst Created: 25-Sep-2000 -Post-History: 23-Feb-2008 - +Post-History: Introduction -============ -This PEP contains guidelines for handling bug reports and feature requests -for the Python project using the tracker at bugs.python.org [1]. + This PEP contains guidelines for handling bug reports to the + Python project at the tracker [1]. Still to be done is to collect + a list of people willing to handle bug reports and their areas of + expertise. -These are guidelines for the developers of Python, not the -submitters of bugs. Those are included as part of the documentation -so they are available in the offline documentation as well as being -available online [2]. + These are guidelines for the developers of Python, not the + submitters of bugs. Those are at + + http://docs.python.org/lib/reporting-bugs.html + + (though this hardly seems the best place). -Tracker Issues -============== -All bug reports and feature requests are handled as issues in the tracker. -Whether they are bugs or requests for new features is indicated by the -type of issue. +Guidelines -Title ------ -This should be a short description of the problem or request. It is worth -correcting it if the originator's title turns out to be misleading. + 1. Make sure the bug category and bug group are correct. If they + are correct, it is easier for someone interested in helping to + find out, say, what all the open Tkinter bugs are. + 2. If it's a minor feature request that you don't plan to address + right away, add it to PEP 42 or ask the owner to add it for + you. If you add the bug to PEP 42, mark the bug as "feature + request", "later", and "closed"; and add a comment to the bug + saying that this is the case (mentioning the PEP explicitly). -Type ----- -This attribute describes the kind of issue being reported. It should be adjusted -if the originator has not set it correctly. The possible issue types are: + XXX do we prefer the tracker or PEP 42? -*feature request* - the issue is not a bug, but a request for additional functionality + 3. Assign the bug a reasonable priority. We don't yet have a + clear sense of what each priority should mean. One rule, + however, is that bugs with priority "urgent" or higher must + be fixed before the next release. -*behavior* - this covers most bugs (including all documentation bugs), where - the behaviour is not desirable or not what the user expected + 4. If a bug report doesn't have enough information to allow you to + reproduce or diagnose it, ask the original submitter for more + information. If the original report is really thin and your + email doesn't get a response after a reasonable waiting period, + you can close the bug. -*crash* - a bug that causes the Python interpreter to crash (segfault/access - violation/bus error) + 5. If you fix a bug, mark the status as "Fixed" and close it. In + the comments, include the SVN revision numbers of the commit(s). + In the SVN checkin message, include the issue number *and* a + normal description of the change, mentioning the contributor + if a patch was applied. -*resource usage* - a bug that causes Python to handle limited resources (memory, file - handles, etc) poorly - -*security* - a bug that may allow the Python interpreter to be used to gain unauthorised - access to information in memory or on the file system (either locally or - remotely) (XXX: is public access to security bugs limited by default?) - - -Severity --------- -This attribute allows the originator to indicate how important the issue is -to them. It should not be adjusted (set the Priority instead). - - -Components ----------- -The originator and developers can use the components list to indicate which -areas of Python or its development tools are affected by the issue. Eventually -developers will be able to subscribe to the tracker so that it automatically -adds them to the nosy list when issues are registered against components they -are interested in. - -For discrepancies between the documentation and the actual behavior, the -components list should be updated if the problem is determined to be an error -in the documentation (and vice-versa if the issue was originally reported as a -documentation problem, but it is later determined that the documentation -accurately describes the desired behavior). - - -Versions --------- -This field is primarily of importance for bug reports - it should indicate -which versions of Python exhibit the problem. Problems which are seen in a -development version should also be flagged appropriately (currently Python 2.6 -for the trunk and Python 3.0 for the py3k branch). - -For feature requests this field is used to flag the target version for the -feature (following a major version release, all open features should be bumped -to target the next version). - - -Status ------- -Open issues are still under consideration. Closed issues have been resolved, -and the resolution field should indicate their final disposition. Pending -issues are intended to be closed soon, but are being held open for a short -period to allow time for some other event (e.g. additional details from the -originator or a decision on whether or not a fix should be backported to the -current maintenance branch). - - -Resolution ----------- -For closed and pending issues, indicates how the issue was (or will be) -resolved. This field should not be set for open issues. In all cases, a -comment should be added when closing the issue to provide additional -detail as to the rationale behind the resolution. - -*accepted* - the feature request has been implemented for the next version - -*rejected* - the feature request was either not described clearly enough to be - implemented, or is not considered a desirable addition to the - language or standard library. - -*fixed* - the reported bug has been fixed for the next version - -*invalid* - the reported bug was either not described clearly enough to be reproduced, - or is actually the intended behaviour - -*works for me* - the reported bug could not be replicated by the developers - -*out of date* - the reported bug applies only to versions of Python which are no longer - supported, or the bug has already been fixed in all versions where it is - possible to fix it (some fixes require new features and hence cannot be - backported to maintenance branches) - -*duplicate* - the reported bug or feature request duplicates an existing issue. The - existing issue should be listed in the Superseder field and closure - comment. - - -Dependencies ------------- -A list of other issues which must be addressed before this issue can be -addressed. - - -Superseder ----------- -A list of other issues which replace this issue. Most commonly used when a new -issue is marked as a duplicate of an existing issue, but can also be used to -indicate when a big issue is split into multiple smaller issues. - - -Assigned To ------------ -The developer with primary responsibility for the issue. Usually this indicate -a request to investigate an initial bug report or to review an attached patch -for a bug report or feature request. It can also be used by developers to -indicate that they intend to address a particular issue. - - -Nosy List ---------- -A list of users that will be automatically notified of changes to the issue. -Modifying or commenting on an issue automatically adds you to the nosy list. - - -Priority --------- -Indicates how significant the bug or feature request is from the point of view -of the developers. - -*immediate* - critical issue requiring release of an immediate patch. Only - likely to be needed for PSF security advisories. - -*urgent* - blocker for release of next version - -*high* - should be fixed for release of next version, but may be delayed at - the discretion of the release manager - -*normal* - to be considered for next version, but may be delayed until later - if it is not implemented in time - -*low* - the issue is valid, but not likely to cause any problems for anyone - - -Keywords --------- -There are a few additional keywords that can be set to aid in performing -searches for certain kinds of issue. These keywords are: - -*64bit* - issue is specific to the 64-bit version of Python - -*easy* - issue should be able to be addressed by newcomers to Python development - -*patch* - a patch file has been attached to the issue for review - - -General Guidelines -================== - -#. Make sure the issue type and components list are correct. If they - are correct, it is easier for someone interested in helping to - find out, say, what all the open Tkinter bugs are. (In the future, - the tracker will allow developers to be automatically added to the - nosy list for issues relating to particular components) - -#. Assign the issue a reasonable priority based on the description above. - -#. If a bug report doesn't have enough information to allow you to - reproduce or diagnose it, post a comment asking the originator for - more information and set the status to pending, and the resolution to - invalid, works for me or out of date (which one makes the most sense - will depend on the specific bug) - If the originator doesn't respond within a reasonable period of time, - the issue can be closed (In the future, pending bug reports will likely - be closed automatically after a certain amount of time in that state - without any activity on the issue). - -#. If you fix a bug, set the status to closed and the resolution to fixed. - In the comments, include the SVN revision numbers of the commit(s). - In the SVN checkin message, include the issue number *and* a - normal description of the change, mentioning the contributor if a patch - was applied. Don't forget to update Misc/NEWS as well. - -#. If uncertain whether or not a fix should be backported to the current - maintenance branch, set the status to pending and ask on python-dev - for advice. Once the fix has been backported (or it has been decided - not to backport it), update the issue appropriately and close it. - -#. For implemented feature requests, the resolution is set to accepted - rather than fixed, but they are otherwise handled the same way as for - bugs. - -#. If you are assigned an issue that you are unable to deal with (either - through a lack of knowledge or time), assign it to someone else if you - think they will be able to deal with it, or else set it to unassigned. - Otherwise it will appear that the issue is being handled, when this is - not in fact the case. + 6. If you are assigned a bug that you are unable to deal with, + assign it to someone else if you think they will be able to + deal with it, otherwise it's probably best to unassign it. References -========== -[1] http://bugs.python.org/ - -[2] http://docs.python.org/lib/reporting-bugs.html + [1] http://bugs.python.org/