PEP: 3 Title: Guidelines for Handling Tracker Issues Version: $Revision: 59412 $ Last-Modified: $Date: 2007-12-08 20:48:07 +1000 (Sat, 08 Dec 2007) $ Author: jeremy@alum.mit.edu (Jeremy Hylton), ncoghlan@gmail.com (Nick Coghlan) Status: Active Type: Process Content-Type: text/x-rst Created: 25-Sep-2000 Post-History: 23-Feb-2008 Introduction ============ This PEP contains guidelines for handling bug reports and feature requests for the Python project using the tracker at bugs.python.org [1]. 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]. 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. 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. 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: *feature request* the issue is not a bug, but a request for additional functionality *behavior* this covers most bugs (including all documentation bugs), where the behaviour is not desirable or not what the user expected *crash* a bug that causes the Python interpreter to crash (segfault/access violation/bus error) *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. References ========== [1] http://bugs.python.org/ [2] http://docs.python.org/lib/reporting-bugs.html