From 0764536b3e3f145bddd08d6d9a2e66977ef8b5f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Sun, 10 Apr 2022 20:56:34 +0200 Subject: [PATCH] Document using Github issues as the issue tracker (#814) --- appendix.rst | 2 + committing.rst | 7 +- communication.rst | 2 +- coverage.rst | 3 +- docquality.rst | 4 +- fixingissues.rst | 2 +- gh-faq.rst | 120 +++++++++++++ gh-labels.rst | 170 ++++++++++++++++++ help.rst | 2 +- index.rst | 2 +- langchanges.rst | 3 +- pullrequest.rst | 33 ++-- setup.rst | 4 +- silencewarnings.rst | 2 +- stdlibchanges.rst | 5 +- tracker.rst | 158 ++++++++-------- triaging.rst | 430 ++++++++------------------------------------ 17 files changed, 478 insertions(+), 471 deletions(-) create mode 100644 gh-faq.rst create mode 100644 gh-labels.rst diff --git a/appendix.rst b/appendix.rst index 793f615c8..9ae0f6e75 100644 --- a/appendix.rst +++ b/appendix.rst @@ -44,6 +44,8 @@ Issue tracking and triaging * :doc:`tracker` * :doc:`triaging` +* :doc:`gh-labels` +* :doc:`gh-faq` Language development in depth ----------------------------- diff --git a/committing.rst b/committing.rst index 9f1951ba7..d1efb4d44 100644 --- a/committing.rst +++ b/committing.rst @@ -26,8 +26,7 @@ to enter the public source tree. Ask yourself the following questions: * **Are the changes acceptable?** If you want to share your work-in-progress code on a feature or bugfix, then you can open a ``WIP``-prefixed pull request, publish patches on - the `issue tracker `_, or create a public - fork of the repository. + the `issue tracker`_, or create a public fork of the repository. * **Do the checks on the pull request show that the test suite passes?** Make sure that all of the status checks are passing. @@ -56,7 +55,7 @@ to enter the public source tree. Ask yourself the following questions: core developers and members of the `Python Triage Team`_ can apply labels to GitHub pull requests). -* **Does the pull request have a label indicating that the submitter has signed the CLA?** +* **Does the pull request pass a check indicating that the submitter has signed the CLA?** Make sure that the contributor has signed a `Contributor Licensing Agreement `_ (CLA), unless their change has no possible intellectual property @@ -247,3 +246,5 @@ the commit message. Here is an example:: Reverts python/cpython#111. Reason: This commit broke the buildbot. + +.. _issue tracker: https://github.com/python/cpython/issues \ No newline at end of file diff --git a/communication.rst b/communication.rst index e09302e45..cd0b38800 100644 --- a/communication.rst +++ b/communication.rst @@ -77,7 +77,7 @@ Most lists are also mirrored at `GMANE `_ and can be read and posted to in various ways, including via web browsers, NNTP newsreaders, and RSS feed readers. -.. _issue tracker: https://bugs.python.org +.. _issue tracker: https://github.com/python/cpython/issues .. _new-bugs-announce: https://mail.python.org/mailman/listinfo/new-bugs-announce .. _python-bugs-list: https://mail.python.org/mailman/listinfo/python-bugs-list .. _python-checkins: https://mail.python.org/mailman/listinfo/python-checkins diff --git a/coverage.rst b/coverage.rst index 09a0d3ab7..de0f979df 100644 --- a/coverage.rst +++ b/coverage.rst @@ -262,8 +262,6 @@ Once you have increased coverage, you need to create an issue on the issue set the "Components" to "Test" and "Versions" to the version of Python you worked on (i.e., the in-development version). -.. _issue tracker: https://bugs.python.org - Measuring coverage of C code with gcov and lcov """"""""""""""""""""""""""""""""""""""""""""""" @@ -292,5 +290,6 @@ about 20 to 30 minutes on a modern computer. Multiple test jobs may not work properly. C coverage reporting has only been tested with a single test process. +.. _issue tracker: https://github.com/python/cpython/issues .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php diff --git a/docquality.rst b/docquality.rst index 29db311b5..6dbbf0e75 100644 --- a/docquality.rst +++ b/docquality.rst @@ -62,8 +62,7 @@ If you see a documentation issue that you would like to tackle, you can: By following the steps in the :ref:`Quick Guide to Pull Requests `, you will learn the workflow for documentation pull requests. -.. _issue tracker: https://bugs.python.org -.. _documentation issues: https://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=6&priority=&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40group=&%40pagesize=100&%40startwith=0&%40sortdir=on&%40queryname=&%40old-queryname=&%40action=search +.. _documentation issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation .. _octocat: https://github.com/logos @@ -136,3 +135,4 @@ without errors. .. _devguide repo: https://github.com/python/devguide .. _devguide GitHub tracker: https://github.com/python/devguide/issues .. _Sphinx: https://www.sphinx-doc.org/ +.. _issue tracker: https://github.com/python/cpython/issues diff --git a/fixingissues.rst b/fixingissues.rst index 7821d4120..148627578 100644 --- a/fixingissues.rst +++ b/fixingissues.rst @@ -20,6 +20,6 @@ discussion to help bring it to a close). Regardless of why the issue is open, you can also always provide useful comments if you do attempt a fix, successful or not. -.. _"easy" issues: https://bugs.python.org/issue?status=1&@sort=-activity&@dispname=Easy%20issues&@startwith=0&@filter=&@group=priority&@columns=id,activity,title,creator,status&keywords=6&@action=search&@pagesize=50 +.. _"easy" issues: https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy .. TODO: add something about no active core developer for the area? diff --git a/gh-faq.rst b/gh-faq.rst new file mode 100644 index 000000000..dd83fe147 --- /dev/null +++ b/gh-faq.rst @@ -0,0 +1,120 @@ +GitHub issues for BPO users +=========================== + +Here are some frequently asked quesions about how to do things in +Github issues that you used to be able to do on `bpo`_. + +Before you ask your own question, make sure you read :doc:`tracker` +and :doc:`triaging` (specifically including :doc:`gh-labels`) as those +pages include a lot of introductory material. + +How to format my comments nicely? +--------------------------------- + +There is a wonderful `beginner guide to writing and formatting on Github +`_. +Highly recommended. + +One pro-tip we can sell you right here is that if you want to paste +some longer log as a comment, attach a file instead (see how below). +If you still insist on pasting it in your comment, do it like this:: + +
+ This is the summary text, click me to expand + + Here goes the long, long text. + It will be collapsed by default! +
+ +How to attach files to an issue? +-------------------------------- + +Drag them into the comment field, wait until the file uploads, and Github +will automatically put a link to your file in your comment text. + +How to link to file paths in the repository when writing comments? +------------------------------------------------------------------ + +Use Markdown links. If you link to the default Github path, the file +will link to the latest current version on the given branch. + +You can get a permanent link to a given revision of a given file by +`pressing "y" `_. + +How to do advanced searches? +---------------------------- + +Use the `Github search syntax`_ or the interactive `advanced search`_ form +that generates search queries for you. + +Where is the "nosy list"? +------------------------- + +Subscribe another person to the issue by tagging them in the comment with +``@username``. + +If you want to subscribe yourself to an issue, click the *🔔 Subscribe* +button in the sidebar. + +Similarly, if you were tagged by somebody else but +decided this issue is not for you, you might click the *🔕 Unsubscribe* +button in the sidebar. + +There is no exact equivalent of the "nosy list" feature, so to preserve +this information during the transfer, we list the previous members of +this list in the first message on the migrated issue. + +How to add issue dependencies? +------------------------------ + +Add a checkbox list like this in the issue description:: + + - [x] #739 + - [ ] https://github.com/octo-org/octo-repo/issues/740 + - [ ] Add delight to the experience when all tasks are complete :tada: + +then those will become sub-tasks on the given issue. Moreover, Github will +automatically mark a task as complete if the other referenced issue is +closed. More details in the `official Github documentation +`_. + +What on Earth is a "mannequin"? +------------------------------- + +For issues migrated to Github from `bpo`_ where the authors or commenters +are not core developers, we opted not to link to their Github accounts +directly. Users not in the `python organization on Github +`_ might not like comments to +appear under their name from an automated import. Others never linked Github on +`bpo`_ in the first place so linking their account, if any, would be impossible. + +In those cases a "mannequin" account is present to help follow the conversation +that happened in the issue. In case the user did share their Github account +name in their `bpo_` profile, we use that. Otherwise, their classic `bpo_` +username is used instead. + +Where did the "Resolution" field go? +------------------------------------ + +Based on historical data we found it not being used very often. + +Where did the "Low", "High", and "Critical" priorities go? +---------------------------------------------------------- + +Based on historical data we found those not being used very often. + +How to find a random issue? +--------------------------- + +This is not supported by Github. + +Where are regression labels? +---------------------------- + +We rarely updated this information and it turned out not to be +particularly useful outside of the change log. + + +.. _bpo: https://bugs.python.org/ +.. _Github search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax +.. _advanced search: https://github.com/search/advanced \ No newline at end of file diff --git a/gh-labels.rst b/gh-labels.rst new file mode 100644 index 000000000..b16ce250c --- /dev/null +++ b/gh-labels.rst @@ -0,0 +1,170 @@ +.. _github-labels: + +Github Labels +============= + +We're using labels on Github to categorize issues and pull requests. +Many labels are shared for both use cases, while some are dedicated +only to one. Below is a possibly inexhaustive list, but it should get +you going. For a full list, see `here `_. + +General purpose labels +---------------------- + +type-behavior + Used for issues/PRs that address unintentional behavior, but do not + pose significant security concerns. Generally, bugfixes will be attached + to a specific issue where the unintended behavior was first reported. + +type-documentation + Used for issues/PRs that exclusively involve changes to + the documentation. Documentation includes `*.rst` files, docstrings, + and code comments. + +type-enhancement + Used for issues/PRs that provide additional functionality + or capabilities beyond the existing specifications. + +type-performance + Used for issues/PRs that provide performance optimizations. + +type-security + Used for issues/PRs that involve critical security issues. Less severe + security concerns can instead use the type-bugfix label. + +type-tests + Used for issues/PRs that exclusively involve changes to the tests. + +OS-Mac / OS-Windows + Used for issues/PRs involving changes which only have an effect upon + a specific operating system. + +spam + Used for issues/PRs that don't include enough eggs or bacon. + +Labels specific to issues +------------------------- + +Priority +^^^^^^^^ + +release-blocker + The highest priority of an issue. If unaddressed, will cause the + release manager to hold releasing a new version of Python. + +deferred-blocker + A release blocker that was pushed one or more releases into the + future. Possibly a temporary workaround was employed, or the version + of Python the issue is affecting is still in alpha or beta stages + of development. + +Component +^^^^^^^^^ + +library + Used for issues involving Python modules in the ``Lib/`` dir. + +documentation + Used for issues involving documentation in the ``Doc/`` dir. + +interpreter-core + Used for issues in interpreter core (``Objects/``, ``Python/``, + ``Grammar/``, and ``Parser/`` dirs). + +extension-modules + Used for issues involving C modules in the ``Modules/`` dir. + +tests + Used for issues involving only Python's regression test suite, i.e. + files in the ``Lib/test/`` dir. + +Other +^^^^^ + +new + Denotes that the issue hasn't been looked at by triagers or core + developers yet. + +easy + Denotes that the issue is a good candidate for a newcomer to address. + + +Labels specific to PRs +---------------------- + +DO-NOT-MERGE + Used on PRs to prevent miss-islington from being able + to automatically merge the pull request. This label is appropriate when a PR + has a non-trivial conflict with the branch it is being merged into. + +expert-asyncio + Used for PRs which involve changes to the asyncio module + or other asynchronous frameworks that utilize it. + +invalid + Used manually for PRs that do not meet basic requirements and + automatically added by bedevere when PR authors attempt to merge maintenace + branches into the main branch. During events such as the October + Hacktoberfest, this label will prevent the PR from counting toward the + author's contributions. + +needs backport to X.Y + Used for PRs which are appropriate to backport to + branches prior to main. Generally, backports to the maintenance branches + are primarily bugfixes and documentation clarifications. Backports to the + security branches are strictly reserved for PRs involving security fixes, such as + crashes, privilege escalation, and DoS. The use of this label will cause + miss-islington to attempt to automatically merge the PR into the branches + specified. + +skip issue + Used for PRs which involve trivial changes, such as typo fixes, + comment changes, and section rephrases. The majority of PRs require + an issue to be attached to, but if there are no code changes and the + section being modified retains the same meaning, this label might be + appropriate. + +skip news + Similar to the skip issue label, this label is used for PRs which + involve trivial changes, backports, or already have a relevant news entry + in another PR. Any potentially impactful changes should have a + corresponding news entry, but for trivial changes it's commonly at the + discretion of the PR author if they wish to opt-out of making one. + +sprint + Used for PRs authored during an in-person sprint, such as + at PyCon, EuroPython, or other official Python events. The label is + used to prioritize the review of those PRs during the sprint. + +stale + Used for PRs that include changes which are no longer relevant, or when the + author hasn't responded to feedback in a long period of time, or when the + reviewer is unresponsive. This label helps core developers quickly identify + PRs that are candidates for closure or require a ping to the author or + reviewer. + +awaiting review + Used for PRs that haven't been reviewed by anyone yet. + +awaiting core review + Used when the PR is authored by a core developer or when a non-core + developer has reviewed the PR, even if they requested changes. + Note that reviewers could have been added manually by a triager or core + developer, or included automatically through use of the `CODEOWNERS + `_ + file. + +awaiting changes + A reviewer required changes to proceed with the PR. + +awaiting change review + The PR author made requested changes, and they are waiting for review. + +awaiting merge + The PR has been approved by a core developer and is ready to merge. + +test-with-buildbots + Used on PRs to test the latest commit with the buildbot fleet. Generally for + PRs with large code changes requiring more testing before merging. This + may take multiple hours to complete. Triagers can also stop a stuck build + using the web interface. diff --git a/help.rst b/help.rst index 731564f09..024359e5b 100644 --- a/help.rst +++ b/help.rst @@ -121,4 +121,4 @@ you detail which conditions triggered it (including the OS name and version, and what you were trying to do), as well as the exact error message you encountered. -.. _issue tracker: https://bugs.python.org +.. _issue tracker: https://github.com/python/cpython/issues diff --git a/index.rst b/index.rst index eac6b58cf..3fc4c381d 100644 --- a/index.rst +++ b/index.rst @@ -341,5 +341,5 @@ Full Table of Contents .. _Jython: https://www.jython.org/ .. _IronPython: https://ironpython.net/ .. _Stackless: https://github.com/stackless-dev/stackless/wiki/ -.. _Issue tracker: https://bugs.python.org/ +.. _Issue tracker: https://github.com/python/cpython/issues .. _open pull requests: https://github.com/python/cpython/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20label%3A%22awaiting%20review%22 diff --git a/langchanges.rst b/langchanges.rst index e5efd92e4..1a29939f1 100644 --- a/langchanges.rst +++ b/langchanges.rst @@ -87,7 +87,8 @@ For some examples on language changes that were accepted please read `Justifying Python Language Changes`_. .. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org/ -.. _issue tracker: https://bugs.python.org +.. _issue tracker: https://github.com/python/cpython/issues .. _PEP Index: https://peps.python.org/ +.. _draft PEP: https://www.python.org/dev/peps/pep-0001/ .. _Status Quo Wins a Stalemate: https://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html .. _Justifying Python Language Changes: https://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html diff --git a/pullrequest.rst b/pullrequest.rst index b8feb4471..f032490d3 100644 --- a/pullrequest.rst +++ b/pullrequest.rst @@ -57,7 +57,7 @@ Here is a quick overview of how you can contribute to CPython: .. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution .. _Open Source: https://opensource.guide/ -.. _create an issue: https://bugs.python.org/ +.. _create an issue: https://github.com/python/cpython/issues .. _CPython: https://github.com/python/cpython .. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/ .. _Create Pull Request: https://help.github.com/articles/creating-a-pull-request/ @@ -140,11 +140,6 @@ You should have already :ref:`set up your system `, git branch -D # delete local branch git push origin -d # delete remote branch -.. note:: - You can still upload a patch to bugs.python.org_, but the GitHub pull request - workflow is **strongly** preferred. - - .. _resolving-merge-conflicts: Resolving Merge Conflicts @@ -314,22 +309,16 @@ license your code for use with Python (you retain the copyright). Here are the steps needed in order to sign the CLA: -1. If you don't have an account on `bugs.python.org `_ - (aka b.p.o), please - `register `_ to create one. - -2. Make sure your GitHub username is listed in the `"Your Details" - `_ - section at b.p.o. +1. Create a change and submit it as a pull request. -3. Fill out and sign the PSF `contributor form`_. The "bugs.python.org username" - requested by the form is the "Login name" field under "Your Details". - -After signing the CLA, please **wait at least one US business day** and -then check the status by going to the `check-python-cla `_ -website. The check will also be run automatically the next time you push changes -to your PR. +2. When ``cpython-cla-bot`` comments on your pull request that commit + authors are required to sign a Contributor License Agreement, click + on the button in the comment to sign it. It's enough to log in through + Github. The process is automatic. +3. After signing, the comment by ``cpython-cla-bot`` will update to + indicate that "all commit authors signed the Contributor License + Agreement. .. _PSF license: https://docs.python.org/dev/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python .. _contributor agreement: https://www.python.org/psf/contrib/ @@ -378,8 +367,6 @@ another so they can easily verify whether their comments have been addressed. The commits will be squashed when the pull request is merged. -.. _issue tracker: https://bugs.python.org - Converting an Existing Patch from b.p.o to GitHub ------------------------------------------------- @@ -510,3 +497,5 @@ Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most often, in a contribution's news entry as well). You may be asked to make these edits on the behalf of the core developer who accepts your pull request. + +.. _issue tracker: https://github.com/python/cpython/issues \ No newline at end of file diff --git a/setup.rst b/setup.rst index bc4ac56f5..3775c5fe2 100644 --- a/setup.rst +++ b/setup.rst @@ -191,7 +191,7 @@ dependencies were missing: for the module's name. If the build failed and you are using a C89 or C99-compliant compiler, -please `open a bug report `_. +please open a bug report on the `issue tracker`_. If you decide to :ref:`build-dependencies`, you will need to re-run both ``configure`` and ``make``. @@ -555,3 +555,5 @@ every rule. ``Tools`` Various tools that are (or have been) used to maintain Python. + +.. _issue tracker: https://github.com/python/cpython/issues \ No newline at end of file diff --git a/silencewarnings.rst b/silencewarnings.rst index 97f4a36b3..8d1ff5bff 100644 --- a/silencewarnings.rst +++ b/silencewarnings.rst @@ -15,4 +15,4 @@ If you decide to tackle a warning you have found, open an issue on the `issue tracker`_ (if one has not already been opened) and say you are going to try and tackle the issue, and then proceed to fix the issue. -.. _issue tracker: https://bugs.python.org +.. _issue tracker: https://github.com/python/cpython/issues \ No newline at end of file diff --git a/stdlibchanges.rst b/stdlibchanges.rst index d91e7cb8f..99e1eda28 100644 --- a/stdlibchanges.rst +++ b/stdlibchanges.rst @@ -11,8 +11,6 @@ module. Changes to pre-existing code is not covered as that is considered a bugfix and thus is treated as a bug that should be filed on the `issue tracker`_. -.. _issue tracker: https://bugs.python.org/ - Adding to a pre-existing module ------------------------------- @@ -37,7 +35,7 @@ suggested. If you have found general acceptance and usefulness for your code from people, you can open an issue on the `issue tracker`_ with the code attached as a -:ref:`patch `. If possible, also submit a +:ref:`pull request `. If possible, also submit a :ref:`contributor agreement `. If a core developer decides that your code would be useful to the general @@ -147,4 +145,5 @@ means that the core developers end up agreeing in general to accepting your PEP) then the module will be added to the stdlib once the creators of the module sign :ref:`contributor agreements `. +.. _issue tracker: https://github.com/python/cpython/issues .. _PEP index: https://peps.python.org/ diff --git a/tracker.rst b/tracker.rst index ded6cfdc8..14b40e57c 100644 --- a/tracker.rst +++ b/tracker.rst @@ -8,14 +8,23 @@ Using the Issue Tracker ======================= If you think you have found a bug in Python, you can report it to the -`issue tracker`_. The `issue tracker`_ is also commonly referred to as -`bugs.python.org` and `bpo`. Documentation bugs can also be reported there. - -You can report bugs with the issue tracker itself to the `meta tracker`_. +`issue tracker`_. The `issue tracker`_ is now hosted on Github, alongside +the codebase and pull requests. Documentation bugs can also be reported there. If you would like to file an issue about this devguide, please do so at the `devguide repo`_. +.. note:: + Python used to use a dedicated `Roundup`_ instance as its issue tracker. + That old bug tracker was hosted under the domain `bugs.python.org` + (sometimes called `bpo` for short). Currently a read-only version is still + available on that domain for historical purposes. All `bpo` data has been + migrated to the current `issue tracker`_ on Github. + + If you're familiar with `bpo` and would like to learn more about Github + issues, please read this page, and the :doc:`triaging` page as they + provide good introductory material. There is also a :doc:`gh-faq` + document to answer some of the more popular questions. Checking if a bug already exists -------------------------------- @@ -30,46 +39,58 @@ already been reported. Checking if the problem is an existing issue will: * determine if additional information, such as how to replicate the issue, is needed -To see if an issue already exists, search the bug database using the -search box on the top of the issue tracker page. An `advanced search`_ is also -available by clicking on "Search" in the sidebar. - +To see if an issue already exists, search the bug database using the search box +above the list of bugs on the issues page. A form-based `advanced search`_ query +builder is also available on Github to help creating the text query you need. 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. - -Once 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: +can report it using the green "New issue" button on the right of the search +box above the list of bugs. If you're not already signed in to Github, it +will ask you to do so now. + +First you need to select what kind of problem you want to report. The +available choices are: + +* **Bug report**: an existing feature isn't working as expected; +* **Documentation**: there is missing, invalid, or misleading documentation; +* **Enhancement**: suggest a new feature for Python; +* **Performance**: something should work faster; +* **Security**: there is a specific kind of weakness open to exploitation + through the points of vulnerability; +* **Tests**: something is wrong with CPython's suite of regression tests; +* **Discuss**: you'd like to learn more about Python, discuss ideas for + possible changes to future Python versions, track core development + discussions, or join a specific special-interest group. + +Depending on your choice, a dedicated form template will appear. In particular, +you'll notice that the last button actually takes you to `Discourse`_ where +many Python-related discussions take place. + +The submission form has only two fields that you need to fill: * 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; otherwise, leave them blank; -* last but not least, you have to describe the problem in detail, including - what you expected to happen, what did happen, and how to replicate the - problem 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). - +* in the **Write** field, describe the problem in detail using hints from + the template that was put in that field for you. Be sure to include what + you expected to happen, what did happen, and how to replicate the + problem. Be sure to include whether any extension modules were involved, + and what hardware and software platform you were using (including version + information as appropriate). In particular, *what version of Python* you + were using. Understanding the issue's progress and status --------------------------------------------- -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. +There is a number of additional fields like **Assignees**, **Labels**, +**Projects**, and **Milestone**. Those are filled by triagers and core +developers, this is covered in the :ref:`triaging` page. You don't need +to worry about those when reporting issues as a Python user. + +You will automatically receive an update each time an action is taken on +the bug, unless you changed your Github notification settings. Disagreement With a Resolution on the Issue Tracker @@ -91,9 +112,6 @@ win any converts. As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. -.. _python-dev: https://mail.python.org/mailman3/lists/python-dev.python.org/ - - .. _helptriage: Helping Triage Issues @@ -109,7 +127,6 @@ 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 ------------------- @@ -136,12 +153,11 @@ This is all helpful as it allows triagers (i.e., 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: +If an issue has a pull request 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 @@ -154,67 +170,53 @@ Doing all of this allows core developers and :ref:`triagers ` 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 triage issues, you might also want to search for issues in modules which you have a working knowledge. Search for the name of a module -in the issue tracker or use the `advanced search`_ to 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. -You may find old issues that can be closed, either because they -are no longer valid or they have a patch that is ready to be committed, -but no one has had the time to do so. - -In the sidebar you can also find links to summaries for easy issues and -issues with a patch. +in the issue tracker or use the `advanced search`_ query builder to search for +specific kinds of issues (e.g. the "Windows" label if you are a Windows +developer, "Extension Modules" if you are familiar with C, etc.). .. _devrole: -Gaining the "Developer" Role on the Issue Tracker -================================================= +Gaining the "Triager" 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 +be given the "Triager" role on the `issue tracker`_. You can make the request +to any person who already has the Triager 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 +Triager 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 +Gaining the Triager 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. +Sub-pages related to the Issue Tracker +====================================== -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. +.. toctree:: + :maxdepth: 1 + gh-labels + gh-faq .. seealso:: | *Issues with Python and documentation* - `The Python issue tracker `_ + `The Python issue tracker `_ Where to report issues about Python. `The New-bugs-announce mailing list `_ @@ -223,17 +225,13 @@ instructions on the `Tracker Development`_ page. `The Python-bugs-list mailing list `_ Where all the changes to issues are reported. - *The meta tracker and its development* - - `The meta tracker `_ - Where to report issues about the tracker itself. - - `The Tracker development wiki page `_ - Instructions about setting up a local instance of the bug tracker. + `The Tracker-discuss mailing list `_ + Discussions about the bug tracker itself. -.. _issue tracker: https://bugs.python.org/ -.. _meta tracker: https://github.com/python/bugs.python.org/issues -.. _advanced search: https://bugs.python.org/issue?@template=search -.. _Tracker Development: https://wiki.python.org/moin/TrackerDevelopment +.. _issue tracker: https://github.com/python/cpython/issues +.. _advanced search: https://github.com/search/advanced .. _devguide repo: https://github.com/python/devguide/issues +.. _Roundup: https://roundup.sourceforge.io/ +.. _Discourse: https://discuss.python.org/ +.. _python-dev: https://mail.python.org/mailman/listinfo/python-dev diff --git a/triaging.rst b/triaging.rst index 43549bae4..852628fef 100644 --- a/triaging.rst +++ b/triaging.rst @@ -6,7 +6,7 @@ Triaging an Issue This section of the devguide documents the `issue tracker`_ for users and developers. -Contributors with the Developer role on the `issue tracker`_ can triage issues +Contributors with the Triager role on the `issue tracker`_ can triage issues directly without any assistance. Additionally, this section provides an overview of the Python triage team. @@ -18,7 +18,7 @@ The Python triage team is a group dedicated towards improving workflow efficiency through thoughtful review and triage of open issues and pull requests. This helps contributors receive timely feedback and enables core developers to focus on reviewed items which reduces their workload. The -expectations of this role expand upon the "Developer" role on the +expectations of this role expand upon the "Triager" role on the `issue tracker`_. The responsibilities listed below are primarily centered around the Python GitHub repositories. This extends beyond CPython, and, as needed, to other repos such as devguide and core-workflow. @@ -55,27 +55,19 @@ Becoming a member of the Python triage team ------------------------------------------- Any Python core developers are welcome to invite a Python contributor to the -Python triage team. Do note that the responsibilities of a Python triager -are more elevated than a developer on bpo. For example, the Python triager -has access to more repositories than just CPython. Triagers will be responsible -to handle not just issues, but also pull requests, and even managing backports. - -Any existing developers on b.p.o can transition into becoming a Python triager. -They can request this to any core developer, and the core developer -can pass the request to the `Python organization admin +Python triage team. Triagers will be responsible to handle not just issues, but +also pull requests, and even managing backports. A Python triager has access to +more repositories than just CPython. + +Any existing active contributor to the Python repository on Github can +transition into becoming a Python triager. They can request this to any core +developer, and the core developer can pass the request to the `Python +organization admin `_ -on GitHub. The request -can be made confidentially via a DM in Discourse, or publicly by opening -an `issue in the core-workflow repository +on GitHub. The request can be made confidentially via a DM in Discourse, or +publicly by opening an `issue in the core-workflow repository `_. -Any contributor who is not already a developer on b.p.o can also self-nominate -to be a member of Python triage team. They can request this to any core developer, -confidentially via DM in Discourse, or publicly by opening an issue in core-workflow. -If a core developer agrees and is willing to vouch for them, the core developer -can pass the request to the GitHub administrator. They should also be added as -developer on bpo. - For every new triager, it would be great to announce them in the python-committers mailing list and core-workflow category in Discourse. `Example announcement `_. @@ -86,106 +78,20 @@ GitHub Labels for PRs ''''''''''''''''''''' An important component of triaging PRs for the CPython repo involves -appropriately categorizing them through the usage of labels. - -Labels for PRs include: - -DO-NOT-MERGE - Used on PRs to prevent miss-islington from being able - to automatically merge the pull request. This label is appropriate when a PR - has a non-trivial conflict with the branch it is being merged into. - -expert-asyncio - Used for PRs which involve changes to the asyncio module - or other asynchronous frameworks that utilize it. - -invalid - Used manually for PRs that do not meet basic requirements and - automatically added by bedevere when PR authors attempt to merge maintenace - branches into the main branch. During events such as the October - Hacktoberfest, this label will prevent the PR from counting toward the - author's contributions. - -needs backport to X.Y - Used for PRs which are appropriate to backport to - branches prior to main. Generally, backports to the maintenance branches - are primarily bugfixes and documentation clarifications. Backports to the - security branches are strictly reserved for PRs involving security fixes, such as - crashes, privilege escalation, and DoS. The use of this label will cause - miss-islington to attempt to automatically merge the PR into the branches - specified. - -OS-X - Used for PRs involving changes which only have an effect upon - a specific operating system. Current variations of the label include - OS-Windows and OS-Mac. - -skip issue - Used for PRs which involve trivial changes, such as typo fixes, - comment changes, and section rephrases. The majority of PRs require - an issue to be attached to, but if there are no code changes and the - section being modified retains the same meaning, this label might be - appropriate. - -skip news - Similar to the skip issue label, this label is used for PRs which - involve trivial changes, backports, or already have a relevant news entry - in another PR. Any potentially impactful changes should have a - corresponding news entry, but for trivial changes it's commonly at the - discretion of the PR author if they wish to opt-out of making one. - -sprint - Used for PRs authored during an in-person sprint, such as - at PyCon, EuroPython, or other official Python events. The label is - used to prioritize the review of those PRs during the sprint. - -stale - Used for PRs that include changes which are no longer relevant or when the - author hasn't responded to feedback in a long period of time. This label - helps core developers quickly identify PRs that are candidates for closure - or require a ping to the author. - -type-bugfix - Used for PRs that address unintentional behavior, but do not - pose significant security concerns. Generally, bugfixes will be attached - to a specific issue where the unintended behavior was first reported. - -type-documentation - Used for PRs that exclusively involve changes to - the documentation. Documentation includes `*.rst` files, docstrings, - and code comments. - -type-enhancement - Used for PRs that provide additional functionality - or capabilities beyond the existing specifications. - -type-performance - Used for PRs that provide performance optimizations. - -type-security - Used for PRs that involve critical security issues. Less severe - security concerns can instead use the type-bugfix label. - -type-tests - Used for PRs that exclusively involve changes to the tests. - -test-with-buildbots - Used on PRs to test the latest commit with the buildbot fleet. Generally for - PRs with large code changes requiring more testing before merging. This - may take multiple hours to complete. Triagers can also stop a stuck build - using the web interface. - -Fields in the Issue Tracker ---------------------------- +appropriately categorizing them through the usage of labels. For this +purpose we're using :doc:`gh-labels`. + +Applying labels for Issues +-------------------------- The major elements found in an issue report include: -* Classification (including *Title*) - These fields categorize the issue. - The fields include *Title*, *Type*, *Stage*, *Components*, and *Version*. +* Classification (including *Title*) - Metadata that lets us categorize + the issue. Apart from the *Title* field, we use some *type-*, *component-*, and + *version-* specific labels. * Process - These fields indicate the state of the issue and its progress - toward resolution. The fields are *Status*, *Resolution*, *Dependencies*, - *Superseder*, *Assigned To*, *Nosy List*, *Priority*, *Keywords*, *Comment*, - *File*, *File Description*, *Remote hg repo*, *GitHub PR*. + toward resolution. The fields are *Status* (open/closed), *Assignees*, + *Comment*, as well as *priority-* and *keyword-* specific labels. * Messages * History @@ -206,12 +112,8 @@ specific type, please do not set a type. | Type | Description | +================+==========================================================+ | behavior | Unexpected behavior, result, or exception. Most bugs | -| | will have this type. | -+----------------+----------------------------------------------------------+ -| compile error | Errors reported by the compiler while compiling Python. | -+----------------+----------------------------------------------------------+ -| crash | Hard crashes of the Python interpreter -- possibly with | -| | a core dump or a Windows error box. | +| | will have this type. This group also includes compile | +| | errors, and crashers. | +----------------+----------------------------------------------------------+ | enhancement | Issues that propose the addition of new functionality, | | | such as new functions, classes, modules, or even new | @@ -223,10 +125,9 @@ specific type, please do not set a type. +----------------+----------------------------------------------------------+ | performance | Situations where too much time is necessary to complete | | | the task. For example, a common task now takes | -| | significantly longer to complete. | -+----------------+----------------------------------------------------------+ -| resource usage | Situations where too many resources (e.g. memory) are | -| | used. | +| | significantly longer to complete. This group also | +| | includes resource usage (e.g. too much memory needed) | +| | issues. | +----------------+----------------------------------------------------------+ | security | Issues that might have security implications. Report | | | security vulnerabilities using the procedure found in | @@ -236,105 +137,45 @@ specific type, please do not set a type. Stage ''''' -A needed next action to advance the issue. The *stage* needn't be set until -it is clear that the issue has been initially triaged and determined work -will be needed. - -+---------------+----------------------------------------------------------+ -| Stage | Description | -+===============+==========================================================+ -| test needed | The steps which are needed to reproduce the issue. The | -| | bug reporter should post a script, instructions, or | -| | example to help someone test or reproduce the issue. | -+---------------+----------------------------------------------------------+ -| needs patch | A patch or pull request is needed to solve the problem | -| | (i.e. fixing the bug or adding the requested | -| | improvement). | -+---------------+----------------------------------------------------------+ -| patch review | A patch or pull request exists, but it needs review. | -| | Any triager or core developer may do the review. | -+---------------+----------------------------------------------------------+ -| commit review | A triager performed a patch review and it looks good. | -| | This signals to core developers the patch or pull | -| | request needs a quick once-over to make sure nothing was | -| | overlooked before committing it. | -+---------------+----------------------------------------------------------+ -| resolved | The issue is considered closed and addressed (e.g. patch | -| | or pull request committed; expected behavior). | -+---------------+----------------------------------------------------------+ +A needed next action to advance the issue. The *stage* on Github issues is +determined by presence of a linked PR and whether the issue is still open +or closed. It is the PR that holds code review-related labels. Components '''''''''' -The area or Python library affected by the issue. This is a multi-select field. - -Choosing certain components, such as `Documentation`, may cause the issue to -be auto-assigned, i.e. the issue tracker may automatically fill in the -`Assigned To`_ field after you press ``Submit changes``. +The area or Python library affected by the issue. A single issue can apply +multiple component labels. One or more components may be selected for an issue: +-------------------+------------------------------------------------------+ | Component | Description | +===================+======================================================+ -| 2to3 (*2.x to* | The 2to3 conversion tool in `Lib/lib2to3`_. | -| *3 conversion* | | -| *tool*) | | -+-------------------+------------------------------------------------------+ -| Build | The build process. | -+-------------------+------------------------------------------------------+ -| ctypes | The ctypes package in `Lib/ctypes`_. | -+-------------------+------------------------------------------------------+ -| Demos and Tools | The files in Tools_ and `Tools/demo`_. | -+-------------------+------------------------------------------------------+ -| Distutils | The distutils package in `Lib/distutils`_. | -+-------------------+------------------------------------------------------+ | Documentation | The documentation in Doc_ (source used to build HTML | | | docs for https://docs.python.org/). | +-------------------+------------------------------------------------------+ -| email | The email package and related modules. | -+-------------------+------------------------------------------------------+ | Extension Modules | C modules in Modules_. | +-------------------+------------------------------------------------------+ -| IDLE | The `Lib/idlelib`_ package. | -+-------------------+------------------------------------------------------+ -| Installation | The installation process. | -+-------------------+------------------------------------------------------+ | Interpreter Core | The interpreter core. | | | The built-in objects in `Objects`_, the `Python`_, | | | `Grammar`_ and `Parser`_ dirs. | +-------------------+------------------------------------------------------+ -| IO | The I/O system, `Lib/io.py`_ and `Modules/_io`_. | -+-------------------+------------------------------------------------------+ | Library (Lib) | Python modules in Lib_. | +-------------------+------------------------------------------------------+ -| Macintosh | The Mac OS X operating system. | -+-------------------+------------------------------------------------------+ -| Regular | The `Lib/re.py`_ and `Modules/_sre.c`_ modules. | -| Expressions | | -+-------------------+------------------------------------------------------+ | Tests | The unittest framework in `Lib/unittest`_ | | | The doctest framework `Lib/doctest.py`_. | | | The CPython tests in `Lib/test`_. | | | The test runner in `Lib/test/regrtest.py`_. | | | The test support utilities in `Lib/test/support`_. | +-------------------+------------------------------------------------------+ -| Tkinter | The `Lib/tkinter`_ package. | -+-------------------+------------------------------------------------------+ -| Unicode | Unicode, codecs, str vs bytes, | -| | `Objects/unicodeobject.c`_. | -+-------------------+------------------------------------------------------+ -| Windows | The Windows operating system. | -+-------------------+------------------------------------------------------+ -| XML | The `Lib/xml`_ package. | -+-------------------+------------------------------------------------------+ Versions '''''''' The known versions of Python that the issue affects and should be fixed for. Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not -applied before Python 3.8.0 is released, this field should be updated to say -Python 3.9 as the version and drop Python 3.8. +applied before Python 3.8.0 is released, this label should be updated to say +``python-3.9`` as the version and drop ``python-3.8``. Priority '''''''' @@ -343,14 +184,8 @@ What is the severity and urgency? +------------------+--------------------------------------------------------+ | Priority | Description | +==================+========================================================+ -| low | This is for low-impact bugs. | -+------------------+--------------------------------------------------------+ | normal | The default value for most issues filed. | +------------------+--------------------------------------------------------+ -| high | Try to fix the issue before the next final release. | -+------------------+--------------------------------------------------------+ -| critical | Should definitely be fixed for next final release. | -+------------------+--------------------------------------------------------+ | deferred blocker | The issue will not hold up the next release, *n*. It | | | will be promoted to a *release blocker* for the | | | following release, *n+1*. | @@ -360,13 +195,11 @@ What is the severity and urgency? | | an alpha release. | +------------------+--------------------------------------------------------+ -As a guideline, *critical* and above are usually reserved for crashes, -serious regressions or breakage of very important APIs. Whether a bug -is a *release blocker* for the current `release schedule`_ is decided by the -release manager. Triagers may recommend this priority and should add the -release manager to the *nosy list*. If needed, consult the -`release schedule`_ and the release's associated PEP for the release -manager's name. +As a guideline, whether a bug is a *release blocker* for the current `release +schedule`_ is decided by the release manager. Triagers may recommend this +priority and should notify the release manager by tagging them in a comment +using ``@username``. If needed, consult the `release schedule`_ and the +release's associated PEP for the release manager's name. Keywords '''''''' @@ -375,56 +208,28 @@ Various informational flags about the issue. Multiple values are possible. +---------------+------------------------------------------------------------+ | Keyword | Description | +===============+============================================================+ -| buildbot | A buildbot triggered the issue being reported. | -+---------------+------------------------------------------------------------+ | easy | Fixing the issue should not take longer than a day for | | | someone new to contributing to Python to solve. | +---------------+------------------------------------------------------------+ -| easy (C) | Fixing the issue should not take longer than a day for | -| | someone new contributing to Python, focused on C. | -+---------------+------------------------------------------------------------+ -| security_issue| This is a security issue or is related to one. The main | -| | difference from the "security" issue type is that this is | -| | a definite security problem that has to be dealt with. | -+---------------+------------------------------------------------------------+ -| PEP 3121 | The issue is related to :pep:`3121`. | -| | Extension Module Initialization and Finalization. | -+---------------+------------------------------------------------------------+ -| newcomer | Issue suitable for newcomer/first time contributors. | -| friendly | Not suitable for experienced contributors. Typically it is | -| | straightforward, well-defined, low-risk, and optionally | -| | someone is able to mentor the new contributor. | -+---------------+------------------------------------------------------------+ -| gsoc | The issue would fit as, or is related to, a GSoC_ project. | -+---------------+------------------------------------------------------------+ -| needs review | The patch or pull request attached to the issue is in need | -| | of a review. | -+---------------+------------------------------------------------------------+ -| patch | There is a patch or pull request attached to the issue. | -+---------------+------------------------------------------------------------+ -| 3.3regression | The issue is a regression in 3.3. | -+---------------+------------------------------------------------------------+ Nosy List ''''''''' A list of people who may be interested in an issue. -It is acceptable to add someone to the nosy list if you think the issue should -be brought to their attention. Use the :ref:`experts` to know who wants to be -added to the nosy list for issues targeting specific areas. +This used to be a feature of the old issue tracker. On Github issues the +same effect is achieved by tagging people in a comment using ``@username``. -If you are logged in and have JavaScript enabled, you can use the ``[+]`` -button to add yourself to the nosy list (remember to click on -"Submit Changes" afterwards). Note that you are added to the nosy -automatically when you submit a message. +It is acceptable to tag someone to if you think the issue should be brought to +their attention. Use the :ref:`experts` to know who wants to be added to the +nosy list for issues targeting specific areas. -The nosy list also has an autocomplete that lets you search from the lists of -developers and :ref:`experts`. The search is case-insensitive and -works for real names, modules, interest areas, etc., and only adds the -username(s) to the nosy once an entry is selected. +If you want to subscribe yourself to an issue, click the *🔔 Subscribe* +button in the sidebar. Similarly, if you were tagged by somebody else but +decided this issue is not for you, you might click the *🔕 Unsubscribe* +button in the sidebar. -Assigned To -''''''''''' +Assignees +''''''''' Who is expected to take the next step in resolving the issue. It is acceptable to assign an issue to someone if the issue cannot move @@ -432,19 +237,30 @@ forward without their help, e.g., they need to make a technical decision to allow the issue to move forward. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. -Note that in order to assign an issue to someone, that person **must** have -the :ref:`Developer role ` on the issue tracker. +Note that in order to assign an issue to someone, that person **must** be +a team member, likely a Triager or a core developer. Dependencies '''''''''''' The issue requires the listed issue(s) to be resolved first before it can move -forward. +forward. This is achieved using checkbox lists in the initial issue description +comment. Long story short, if you add this:: + + - [x] #739 + - [ ] https://github.com/octo-org/octo-repo/issues/740 + - [ ] Add delight to the experience when all tasks are complete :tada: + +then those will become sub-tasks on the given issue. Moreover, Github will +automatically mark a task as complete if the other referenced issue is +closed. + +More details in the `official Github documentation +`_. Superseder '''''''''' -The issue is a duplicate of the listed issue(s). The issue should just be the -number, not the b.p.o URL or "issueXXXXX". If this is set, the Resolution should -be set to *Duplicate*. +The issue is a duplicate of the listed issue(s). To make Github mark +an issue as duplicate, write "Duplicate of #xxxx" in a comment. Status '''''' @@ -454,68 +270,14 @@ Status +===============+============================================================+ | open | Issue is not resolved. | +---------------+------------------------------------------------------------+ -| pending | The issue is blocked until someone (often the | -| | :abbr:`OP (original poster)`) provides some critical | -| | information; the issue will be closed after a set amount | -| | time if no reply comes in. | -| | | -| | Useful when someone opens an issue that lacks enough | -| | information to reproduce the bug reported. Requesting | -| | additional information and setting status to *pending* | -| | indicates that the issue should be closed if the necessary | -| | information is not provided in a timely manner (i.e. one | -| | month). | -+---------------+------------------------------------------------------------+ | closed | The issue has been resolved (somehow). | +---------------+------------------------------------------------------------+ -Resolution -'''''''''' -Why the issue is in its current state. This is not usually used for issues -with the "open" status. - -+---------------+------------------------------------------------------------+ -| Resolution | Description | -+===============+============================================================+ -| open | Issue is not resolved. | -+---------------+------------------------------------------------------------+ -| duplicate | Duplicate of another issue; should have the *Superseder* | -| | field filled out. | -+---------------+------------------------------------------------------------+ -| fixed | A fix for the issue was committed. | -+---------------+------------------------------------------------------------+ -| later | Issue is to be worked on in a later release cycle. | -+---------------+------------------------------------------------------------+ -| not a bug | For some reason the issue is invalid (e.g. the perceived | -| | problem is not a bug in Python). | -+---------------+------------------------------------------------------------+ -| out of date | The issue has already been fixed, or the problem doesn't | -| | exist anymore for other reasons. | -+---------------+------------------------------------------------------------+ -| postponed | Issue will not be worked on at the moment but in a future | -| | minor release version. | -+---------------+------------------------------------------------------------+ -| rejected | Issue was rejected (especially for feature requests). | -+---------------+------------------------------------------------------------+ -| remind | The issue is acting as a reminder for someone. | -+---------------+------------------------------------------------------------+ -| wont fix | Issue will not be fixed, typically because it would cause | -| | a backwards-compatibility problem. | -+---------------+------------------------------------------------------------+ -| works for me | Bug cannot be reproduced. | -+---------------+------------------------------------------------------------+ - -Mercurial Repository +Linked pull requests '''''''''''''''''''' -Deprecated: HTTP link to a Mercurial repository that contains a patch for the issue. - -New repository links should not be added to new or existing issues. - -GitHub PR -''''''''' -GitHub pull request number or full URL to a pull request. This field is -usually not needed as links are automatically created between issues and PRs -when an issue number is mentioned in the PR description or a commit message. +A link might be added manually using the cog icon next to this field. +Most commonly though, if the PR includes "Fixes #xxx" in its description, +the link will be added automatically. Generating Special Links in a Comment ------------------------------------- @@ -525,49 +287,13 @@ a link to relevant web pages. +-------------------------------------------------------------+-------------------------------------------------------+ | Comment abbreviation | Description | +=============================================================+=======================================================+ -| ``#``, | Links to the tracker issue ````. | -| ``bpo-``, | | -| ``issue``, or | | -| ``issue `` | | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``msg`` | Links to the tracker message ````. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``PR ``, | Links to `GitHub pull requests`_. | -| ``PR-``, | | -| ``PR``, | | -| ``GH ``, | | -| ``GH-``, | | -| ``GH``, or | | -| ``pull request `` | | -+-------------------------------------------------------------+-------------------------------------------------------+ -| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git or Mercurial changeset identifier and | -| | generates a link to changeset ```` on GitHub | -| | or https://hg.python.org/. The ``git`` and ``hg`` | -| | prefixes can also be used to disambiguate, and must | -| | precede the number without spaces. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``r``, | Indicates a legacy Subversion revision number, | -| ``rev``, or | a reference to a changeset that was checked in prior | -| ``revision `` | to 2011-03-05 when the official Python source code | -| | repositories were migrated from the | -| | :abbr:`svn (Subversion)` | -| | :abbr:`VCS (version control system)` to Mercurial. | -| | The issue tracker automatically translates the legacy | -| | svn revision ```` to its corresponding | -| | Mercurial changeset identifier. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``Dir/file.ext`` or | Links to files in the | -| ``Dir/file.ext:NNN`` | `Python source code repositories`_, possibly linking | -| | to the line number specified after the ``:``. | -| | ``3.6/Dir/file.ext`` will generate a link with ``3.6``| -| | as branch. | +| ``#``, | Links to the tracker issue or PR ```` (they | +| ``GH-`` | share the same sequence of integers on Github). | +-------------------------------------------------------------+-------------------------------------------------------+ -| ``PEP `` or | Link to the :abbr:`PEP (Python Enhancement Proposal)` | -| ``PEP`` | ````. | +| ``BPO-`` | Links to the old bug tracker at bugs.python.org. | +-------------------------------------------------------------+-------------------------------------------------------+ -| ``devguide``, | Links to the Devguide, this page, and this section | -| ``devguide/triaging``, or | respectively. | -| ``devguide/triaging#generating-special-links-in-a-comment`` | | +| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git changeset identifier and | +| | generates a link to changeset ```` on GitHub. | +-------------------------------------------------------------+-------------------------------------------------------+ Checklist for Triaging @@ -585,9 +311,8 @@ Checklist for Triaging - Versions: set if known, leave blank if unsure. Multiple items may be set. * Review and set process fields - Status - - Resolution - Superseder - - Assigned To + - Assignees - Nosy List - Priority - Keywords @@ -630,3 +355,4 @@ Checklist for Triaging .. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org .. _release schedule: https://devguide.python.org/#status-of-python-branches .. _PSF Code of Conduct: https://www.python.org/psf/conduct/ +.. _PEP 3121: https://www.python.org/dev/peps/pep-3121/