From c7de522f62e787f6def8264ee630e882029bb259 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:16:31 -0800 Subject: [PATCH 01/42] First draft: make text easier to skim --- committing.rst | 379 +++++++++++++++++++++---------------------------- 1 file changed, 158 insertions(+), 221 deletions(-) diff --git a/committing.rst b/committing.rst index 773dd66cc9..3a15b233f9 100644 --- a/committing.rst +++ b/committing.rst @@ -5,212 +5,151 @@ Accepting Pull Requests .. highlight:: none -This page is aimed to core developers, and covers the steps required to -accept, merge, and possibly backport a pull request on the main repository. - -Is the PR ready to be accepted? -------------------------------- - -Before a PR is accepted, you must make sure it is ready to enter the public -source tree. Use the following as a checklist of what to check for before -merging (details of various steps can be found later in this document): - -#. Has the submitter signed the CLA? - (delineated by a label on the pull request) -#. Did the test suite pass? (delineated by a pull request check) -#. Did code coverage increase or stay the same? - (delineated by a comment on the pull request) -#. Are the changes acceptable? -#. Was ``configure`` regenerated (if necessary)? -#. Was ``pyconfig.h.in`` regenerated (if necessary)? -#. Was the submitter added to ``Misc/ACKS`` (as appropriate)? -#. Was an entry added under ``Misc/NEWS.d/next`` (as appropriate)? -#. Was "What's New" updated (as appropriate)? -#. Were appropriate labels added to signify necessary backporting of the - pull request? -#. Was the pull request first made against the ``master`` branch? - -.. note:: - If you want to share your work-in-progress code on a feature or bugfix, - either open a ``WIP``-prefixed PR, publish patches on the - `issue tracker`_ or create a public fork of the repository. - -.. _issue tracker: https://bugs.python.org - - -Does the test suite still pass? -''''''''''''''''''''''''''''''' - -You must :ref:`run the whole test suite ` to ensure that it -passes before merging any code changes. - -.. note:: - You really need to run the **entire** test suite. Running a single test - is not enough as the changes may have unforeseen effects on other tests - or library modules. - - Running the entire test suite doesn't guarantee that the changes - will pass the :ref:`continuous integration ` tests, as those - will exercise more possibilities still (such as different platforms or - build options). But it will at least catch non-build specific, - non-platform specific errors, therefore minimizing the chance for - breakage. - - -Patch checklist -''''''''''''''' - -You should also :ref:`run patchcheck ` to perform a quick -sanity check on the changes. - - -Handling Others' Code ---------------------- - -As a core developer you will occasionally want to commit a patch created by -someone else. When doing so you will want to make sure of some things. - -First, make sure the patch is in a good state. Both :ref:`patch` and -:ref:`helptriage` -explain what is to be expected of a patch. Typically patches that get cleared by -triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS.d`` -entries (which a core developer should make sure are updated appropriately). - -Second, make sure the patch does not break backwards-compatibility without a -good reason. This means :ref:`running the entire test suite ` to -make sure everything still passes. It also means that if semantics do change -there must be a good reason for the breakage of code the change will cause -(and it **will** break someone's code). If you are unsure if the breakage -is worth it, ask on python-dev. - -Third, ensure the patch is attributed correctly with the contributor's -name in ``Misc/ACKS`` if they aren't already there (and didn't add themselves -in their patch) and by mentioning "Patch by " in the ``Misc/NEWS.d`` entry -and the check-in message. If the patch has been heavily modified then "Initial -patch by " is an appropriate alternate wording. GitHub now supports `multiple -authors `_ -in a commit. Add ``Co-authored-by: name `` at the end of the commit message. - -If you omit correct attribution in the initial check-in, then update ``ACKS`` -and ``NEWS.d`` in a subsequent check-in (don't worry about trying to fix the -original check-in message in that case). - -Finally, make sure that the submitter of the -patch has a CLA in place (indicated by an asterisk following their username -in the `issue tracker`_ or by the "CLA Signed" label on the pull request). -If the submitter lacks a signed CLA and the patch is non-trivial, direct them -to the electronic `Contributor Licensing Agreement`_ -to ensure the PSF has the appropriate authorizations in place to relicense -and redistribute their code. - - -Contributor Licensing Agreements --------------------------------- - -Always get a `Contributor Licensing Agreement`_ (CLA) signed unless the -change has no possible intellectual property associated with it (e.g. fixing -a spelling mistake in documentation). Otherwise it is simply safer from a -legal standpoint to require the contributor to sign the CLA. - -These days, the CLA can be signed electronically through the form linked -above, and this process is strongly preferred to the old mechanism that -involved sending a scanned copy of the signed paper form. - -As discussed on the PSF Contribution_ page, it is the CLA itself that gives -the PSF the necessary relicensing rights to redistribute contributions under -the Python license stack. This is an additional permission granted above and -beyond the normal permissions provided by the chosen open source license. - -Some developers may object to the relicensing permissions granted to the PSF -by the CLA. They're entirely within their rights to refuse to sign the CLA -on that basis, but that refusal *does* mean we **can't accept their patches** -for inclusion. - - -.. _Contribution: https://www.python.org/psf/contrib/ -.. _Contributor Licensing Agreement: - https://www.python.org/psf/contrib/contrib-form/ - - -Checking if the CLA has been received -------------------------------------- - -To check if a contributor's CLA has been received, go to the following website:: - - https://check-python-cla.herokuapp.com/ - -and put in their GitHub username. - -For further questions about the CLA process, write to: contributors@python.org. - - -What's New and News Entries ---------------------------- +This page is a step-by-step guide for core developers who need to assess, +merge, and possibly backport a pull request on the main repository. + +Assessing a Pull Request +-------------- + +Before you can accept a PR, you need to make sure that it is ready to enter +the public source tree. Ask yourself the following questions: + +#. **Was the pull request first made against the ``master`` branch?** The + only branch that receives new features is ``master``, the in-development + branch. + +#. **Are there comments on the PR?** Look for explanations about whether + the code coverage increased or stayed the same. + +#. **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 PR, + publish patches on the `issue tracker `_, or + create a public fork of the repository. + +#. **Does the check on the PR show that the test suite passes?** :ref:`Run the + entire test suite ` to ensure that it passes. Running a single + test is not enough since the changes may have unforeseen effects on other + tests or library modules. + +#. **Is the patch in a good state?** Check :ref:`patch` and + :ref:`helptriage` to review what is expected of a patch. + +#. **Do the changes meet the requirements of the patch checklist?** :ref:`Run + patchcheck ` to perform a quick confidence check on the changes. + +#. **Does the patch break backwards-compatibility without a strong + reason?** :ref:`Run the entire test suite ` to + make sure that everything still passes. If there is a change to the + semantics, then there needs to be a strong reason, because it will + cause some peoples' code to break. If you are unsure if the breakage + is worth it, then ask on python-dev. + +#. **Were ``configure`` and ``pyconfig.h.in`` regenerated?** + Regnenerate them if necessary. + +#. **Were appropriate labels added to signify necessary backporting of the + pull request?** If it is determined that a pull request needs to be + backported into one or more of the maintenance branches, then a core + developer can apply the label ``needs backport to X.Y`` to the pull + request. Once the backport pull request has been created, remove the + ``needs backport to X.Y`` label from the original pull request. (Only + core developers and members of the `Python Triage Team`_ can apply + labels to GitHub pull requests). + +#. **Does the PR have a label 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 associated with it (e.g. fixing a spelling mistake in + documentation). To check if a contributor’s CLA has been received, go + to `Check Python CLA `_ and + put in their GitHub username. For further questions about the CLA + process, write to: contributors@python.org. + +#. **Was the contributor added to ``Misc/ACKS``?** Make sure that + the patch is attributed correctly with the contributor's name in + ``Misc/ACKS``. If the patch has been heavily modified, then "Initial + patch by " is an appropriate alternate wording. GitHub now + supports `multiple authors + `_ + in a commit. Add ``Co-authored-by: name `` at the end + of the commit message. + +#. **Were ``What's New in Python`` (in ``Doc/whatsnew/``) and + ``Misc/NEWS.d/next``updated?** If the change is particularly interesting + for end users (e.g. new features, significant improvements, or + backwards-incompatible changes), then an entry in the + ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added + as well. Changes that affect only documentation generally do not require + a news entry. (See the following section for more information.) + +Updating News and What's New in Python +-------------------------------------- Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. If the change is particularly interesting for end users (e.g. new features, -significant improvements, or backwards-incompatible changes), an entry in +significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added -as well. Changes that affect documentation only generally do not require +as well. Changes that affect documentation only generally do not require a news entry. There are two notable exceptions to this general principle, and they -both relate to changes that *already* have a news entry, and have not yet -been included in any formal release (including alpha and beta releases). -These exceptions are: - -* If a change is reverted prior to release, then the corresponding entry - is simply removed. Otherwise, a new entry must be added noting that the - change has been reverted (e.g. when a feature is released in an alpha and - then cut prior to the first beta). - -* If a change is a fix (or other adjustment) to an earlier unreleased change - and the original news entry remains valid, then no additional entry is - needed. - -Needing a What's New entry almost always means that a change is *not* -suitable for inclusion in a maintenance release. A small number of -exceptions have been made for Python 2.7 due to the long support period - -when implemented, these changes *must* be noted in the "New Additions in -Python 2.7 Maintenance Releases" section of the Python 2.7 What's New -document. +both relate to changes that: + +* Already have a news entry +* Have not yet been included in any formal release (including alpha + and beta releases) + +These are the two exceptions: + +#. **If a change is reverted prior to release**, then the corresponding + entry is simply removed. Otherwise, a new entry must be added noting + that the change has been reverted (e.g. when a feature is released in + an alpha and then cut prior to the first beta). + +#. **If a change is a fix (or other adjustment) to an earlier unreleased + change and the original news entry remains valid**, then no additional + entry is needed. + +If a change needs an entry in ``What's New in Python``, then it very +likely *not* suitable for including in a maintenance release. News entries go into the ``Misc/NEWS.d`` directory as individual files. The news entry can be created by using `blurb-it `_, or the `blurb `_ tool and its ``blurb add`` command. -If you are unable to use the tool you can create the news entry file manually. -The ``Misc/NEWS.d`` directory contains a sub-directory named ``next`` which -itself contains various sub-directories representing classifications for what -was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the -standard library). The file name itself should be of the format +If you are unable to use the tool, then you can create the news entry file +manually. The ``Misc/NEWS.d`` directory contains a sub-directory named +``next``, which contains various sub-directories representing classifications +for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating +to the standard library). The file name itself should be in the format ``.bpo-..rst``: * ```` is today's date joined with a ``-`` to the current - time, in ``YYYY-MM-DD-hh-mm-ss`` format, e.g. ``2017-05-27-16-46-23`` -* ```` is the issue number the change is for, e.g. ``12345`` - for ``bpo-12345`` -* ```` is some "unique" string to guarantee the file name is - unique across branches, e.g. ``Yl4gI2`` (typically six characters, but it can - be any length of letters and numbers, and its uniqueness can be satisfied by - typing random characters on your keyboard) - -So a file name may be + time, in ``YYYY-MM-DD-hh-mm-ss`` format (e.g. ``2017-05-27-16-46-23``). +* ```` is the issue number the change is for (e.g. ``12345`` + for ``bpo-12345``). +* ```` is a unique string to guarantee that the file name is + unique across branches (e.g. ``Yl4gI2``). (It is typically six characters + long, but it can be any length of letters and numbers. Its uniqueness + can be satisfied by typing random characters on your keyboard.) + +As a result, a file name can look something like ``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.bpo-12345.Yl4gI2.rst``. The contents of a news file should be valid reStructuredText. An 80 character column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue -number as it's part of the file name itself. You can use -:ref:`inline markups ` too. Example news entry:: +number since it is part of the file name. You can use +:ref:`inline markups ` too. Here is an example of a news +entry:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. -The inline Sphinx roles like ``:func:`` can be used to assist readers in finding -more information. You can build html and verify that the link target is -appropriate by using :ref:`make html `. +The inline Sphinx roles like ``:func:`` can be used help readers +find more information. You can build html and verify that the +link target is appropriate by using :ref:`make html `. While Sphinx roles can be beneficial to readers, they are not required. Inline ````code blocks```` can be used instead. @@ -222,30 +161,28 @@ Working with Git_ .. seealso:: :ref:`gitbootcamp` -As a core developer, the ability to push changes to the official Python -repositories means you have to be more careful with your workflow: +As a core developer, you have the ability to push changes to the official +Python repositories, so you need to be careful with your workflow: -* You should not push new branches to the main repository. You can still use - them in your fork that you use for development of patches; you can - also push these branches to a **separate** public repository that will be - dedicated to maintenance of the work before the work gets integrated in the - main repository. +* **You should not push new branches to the main repository.** You can + still use them in the fork that you use for the development of patches. + You can also push these branches to a **separate** public repository + for maintenance work before it is integrated into the main repository. -* You should not commit directly into the ``master`` branch, or any of the - maintenance branches (currently ``3.9`` and ``3.8``). - You should commit against your own feature branch, and create a pull request. +* **You should not commit directly into the ``master`` branch, or any of the + maintenance branches (currently ``3.9`` and ``3.8``).** You should commit + against your own feature branch, and then create a pull request. -* For a small change, you can make a quick edit through the GitHub web UI. +* **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will - create a new branch in the **main** CPython repo (not your fork). Please - delete this newly created branch after it has been merged into the + create a new branch in the **main** CPython repo rather than in your fork. + Delete this newly created branch after it has been merged into the ``master`` branch or any of the maintenance branches. To keep the CPython - repo tidy, please try to limit the existence of the new branch to, at most, - a few days. + repo tidy, remove the new branch within a few days. -It is recommended to keep a fork of the main repository around, as it allows -simple reversion of all local changes (even "committed" ones) if your local -clone gets into a state you aren't happy with. +Keep a fork of the main repository, since it will allow you to revert all +local changes (even committed ones) if you're not happy with your local +clone. .. _Git: https://git-scm.com/ @@ -253,65 +190,65 @@ clone gets into a state you aren't happy with. .. _committing-active-branches: -Active branches -''''''''''''''' +Seeing active branches +'''''''''''''''''''''' -If you do ``git branch`` you will see a :ref:`list of branches `. -``master`` is the in-development branch, and is the only branch that receives -new features. The other branches only receive bug fixes or security fixes. +If you use ``git branch``, then you will see a :ref:`list of branches +`. The only branch that receives new features is +``master``, the in-development branch. The other branches receive only +bug fixes or security fixes. .. _branch-merge: -Backporting Changes to an Older Version +Backporting changes to an older version ''''''''''''''''''''''''''''''''''''''' -When it is determined that a pull request needs to be backported into one or -more of the maintenance branches, a core developer can apply the labels +If it is determined that a pull request needs to be backported into one or +more of the maintenance branches, then a core developer can apply the label ``needs backport to X.Y`` to the pull request. After the pull request has been merged, miss-islington (bot) will first try to -do the backport automatically. In case that miss-islington is unable to do it, +do the backport automatically. If miss-islington is unable to do it, then the pull request author or the core developer who merged it should look into backporting it themselves, using the backport generated by cherry_picker.py_ as a starting point. -The commit hash can be obtained from the original pull request, or by using -``git log`` on the ``master`` branch. -To display the 10 most recent commit hashes and their first line of the commit -message:: +You can get the commit hash from the original pull request, or you can use +``git log`` on the ``master`` branch. To display the 10 most recent commit +hashes and their first line of the commit, use the following command:: git log -10 --oneline .. _backport-pr-title: Prefix the backport pull request with the branch, and reference the pull request -number from ``master``, for example:: +number from ``master``. Here is an example:: [3.9] bpo-12345: Fix the Spam Module (GH-NNNN) Note that cherry_picker.py_ adds the branch prefix automatically. Once the backport pull request has been created, remove the -``needs backport to X.Y`` label from the original pull request. (Only Core -Developers and members of the `Python Triage Team`_ can apply labels to GitHub +``needs backport to X.Y`` label from the original pull request. (Only core +developers and members of the `Python Triage Team`_ can apply labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/cherry-picker .. _`Python Triage Team`: https://devguide.python.org/triaging/#python-triage-team -Reverting a Merged Pull Request +Reverting a merged pull request ''''''''''''''''''''''''''''''' To revert a merged pull request, press the ``Revert`` button at the bottom of -the pull request. It will bring up the page to create a new pull request where -the commit can be reverted. It also creates a new branch on the main CPython -repository. Delete the branch once the pull request has been merged. +the pull request. That will bring up the page to create a new pull request where +the commit can be reverted. It also creates a new branch on the main CPython +repository. Delete the branch once the pull request has been merged. Always include the reason for reverting the commit to help others understand -why it was done. The reason should be included as part of the commit message, -for example:: +why it was done. The reason should be included as part of the commit message. +Here is an example:: Revert bpo-NNNN: Fix Spam Module (GH-111) From b6acaca9edea57a7c6b7a087273631c119b12c0f Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:19:50 -0800 Subject: [PATCH 02/42] Change list spacing: learning rst --- committing.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/committing.rst b/committing.rst index 3a15b233f9..a8124a7d8e 100644 --- a/committing.rst +++ b/committing.rst @@ -17,7 +17,6 @@ the public source tree. Ask yourself the following questions: #. **Was the pull request first made against the ``master`` branch?** The only branch that receives new features is ``master``, the in-development branch. - #. **Are there comments on the PR?** Look for explanations about whether the code coverage increased or stayed the same. From a3a92f71676c5fd92fc199847e579790019bf22f Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:22:43 -0800 Subject: [PATCH 03/42] Learning rst --- committing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index a8124a7d8e..103d187607 100644 --- a/committing.rst +++ b/committing.rst @@ -15,8 +15,8 @@ Before you can accept a PR, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: #. **Was the pull request first made against the ``master`` branch?** The - only branch that receives new features is ``master``, the in-development - branch. + only branch that receives new features is ``master``, the in-development + branch. #. **Are there comments on the PR?** Look for explanations about whether the code coverage increased or stayed the same. From e0742b173f034215dca49e75020d3d1353ce6d81 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:23:36 -0800 Subject: [PATCH 04/42] Learning rst --- committing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/committing.rst b/committing.rst index 103d187607..4fcbe84f2b 100644 --- a/committing.rst +++ b/committing.rst @@ -17,6 +17,7 @@ the public source tree. Ask yourself the following questions: #. **Was the pull request first made against the ``master`` branch?** The only branch that receives new features is ``master``, the in-development branch. + #. **Are there comments on the PR?** Look for explanations about whether the code coverage increased or stayed the same. From 0bd92269c7c3aeb3a966c3960871647f31438e6e Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:26:12 -0800 Subject: [PATCH 05/42] Fix list indentation --- committing.rst | 94 +++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/committing.rst b/committing.rst index 4fcbe84f2b..1c5bb847bd 100644 --- a/committing.rst +++ b/committing.rst @@ -19,68 +19,68 @@ the public source tree. Ask yourself the following questions: branch. #. **Are there comments on the PR?** Look for explanations about whether - the code coverage increased or stayed the same. + the code coverage increased or stayed the same. #. **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 PR, - publish patches on the `issue tracker `_, or - create a public fork of the repository. + code on a feature or bugfix, then you can open a ``WIP``-prefixed PR, + publish patches on the `issue tracker `_, or + create a public fork of the repository. #. **Does the check on the PR show that the test suite passes?** :ref:`Run the - entire test suite ` to ensure that it passes. Running a single - test is not enough since the changes may have unforeseen effects on other - tests or library modules. + entire test suite ` to ensure that it passes. Running a single + test is not enough since the changes may have unforeseen effects on other + tests or library modules. #. **Is the patch in a good state?** Check :ref:`patch` and - :ref:`helptriage` to review what is expected of a patch. + :ref:`helptriage` to review what is expected of a patch. #. **Do the changes meet the requirements of the patch checklist?** :ref:`Run - patchcheck ` to perform a quick confidence check on the changes. + patchcheck ` to perform a quick confidence check on the changes. #. **Does the patch break backwards-compatibility without a strong - reason?** :ref:`Run the entire test suite ` to - make sure that everything still passes. If there is a change to the - semantics, then there needs to be a strong reason, because it will - cause some peoples' code to break. If you are unsure if the breakage - is worth it, then ask on python-dev. + reason?** :ref:`Run the entire test suite ` to + make sure that everything still passes. If there is a change to the + semantics, then there needs to be a strong reason, because it will + cause some peoples' code to break. If you are unsure if the breakage + is worth it, then ask on python-dev. #. **Were ``configure`` and ``pyconfig.h.in`` regenerated?** - Regnenerate them if necessary. + Regnenerate them if necessary. #. **Were appropriate labels added to signify necessary backporting of the - pull request?** If it is determined that a pull request needs to be - backported into one or more of the maintenance branches, then a core - developer can apply the label ``needs backport to X.Y`` to the pull - request. Once the backport pull request has been created, remove the - ``needs backport to X.Y`` label from the original pull request. (Only - core developers and members of the `Python Triage Team`_ can apply - labels to GitHub pull requests). + pull request?** If it is determined that a pull request needs to be + backported into one or more of the maintenance branches, then a core + developer can apply the label ``needs backport to X.Y`` to the pull + request. Once the backport pull request has been created, remove the + ``needs backport to X.Y`` label from the original pull request. (Only + core developers and members of the `Python Triage Team`_ can apply + labels to GitHub pull requests). #. **Does the PR have a label 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 associated with it (e.g. fixing a spelling mistake in - documentation). To check if a contributor’s CLA has been received, go - to `Check Python CLA `_ and - put in their GitHub username. For further questions about the CLA - process, write to: contributors@python.org. + CLA?** Make sure that the contributor has signed a `Contributor Licensing + Agreement`_ (CLA), unless their change has no possible intellectual + property associated with it (e.g. fixing a spelling mistake in + documentation). To check if a contributor’s CLA has been received, go + to `Check Python CLA `_ and + put in their GitHub username. For further questions about the CLA + process, write to: contributors@python.org. #. **Was the contributor added to ``Misc/ACKS``?** Make sure that - the patch is attributed correctly with the contributor's name in - ``Misc/ACKS``. If the patch has been heavily modified, then "Initial - patch by " is an appropriate alternate wording. GitHub now - supports `multiple authors - `_ - in a commit. Add ``Co-authored-by: name `` at the end - of the commit message. + the patch is attributed correctly with the contributor's name in + ``Misc/ACKS``. If the patch has been heavily modified, then "Initial + patch by " is an appropriate alternate wording. GitHub now + supports `multiple authors + `_ + in a commit. Add ``Co-authored-by: name `` at the end + of the commit message. #. **Were ``What's New in Python`` (in ``Doc/whatsnew/``) and - ``Misc/NEWS.d/next``updated?** If the change is particularly interesting - for end users (e.g. new features, significant improvements, or - backwards-incompatible changes), then an entry in the - ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added - as well. Changes that affect only documentation generally do not require - a news entry. (See the following section for more information.) + ``Misc/NEWS.d/next``updated?** If the change is particularly interesting + for end users (e.g. new features, significant improvements, or + backwards-incompatible changes), then an entry in the + ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added + as well. Changes that affect only documentation generally do not require + a news entry. (See the following section for more information.) Updating News and What's New in Python -------------------------------------- @@ -102,13 +102,13 @@ both relate to changes that: These are the two exceptions: #. **If a change is reverted prior to release**, then the corresponding - entry is simply removed. Otherwise, a new entry must be added noting - that the change has been reverted (e.g. when a feature is released in - an alpha and then cut prior to the first beta). + entry is simply removed. Otherwise, a new entry must be added noting + that the change has been reverted (e.g. when a feature is released in + an alpha and then cut prior to the first beta). #. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original news entry remains valid**, then no additional - entry is needed. + change and the original news entry remains valid**, then no additional + entry is needed. If a change needs an entry in ``What's New in Python``, then it very likely *not* suitable for including in a maintenance release. From 6e26e24e61daa0f5f8e939111fe45c8b138d1b73 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:31:21 -0800 Subject: [PATCH 06/42] Remove monospace when conflicted with bold --- committing.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/committing.rst b/committing.rst index 1c5bb847bd..0ff022b700 100644 --- a/committing.rst +++ b/committing.rst @@ -14,7 +14,7 @@ Assessing a Pull Request Before you can accept a PR, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: -#. **Was the pull request first made against the ``master`` branch?** The +#. **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. @@ -44,7 +44,7 @@ the public source tree. Ask yourself the following questions: cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. -#. **Were ``configure`` and ``pyconfig.h.in`` regenerated?** +#. **Were configure and pyconfig.h.in regenerated?** Regnenerate them if necessary. #. **Were appropriate labels added to signify necessary backporting of the @@ -65,7 +65,7 @@ the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to: contributors@python.org. -#. **Was the contributor added to ``Misc/ACKS``?** Make sure that +#. **Was the contributor added to Misc/ACKS?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial patch by " is an appropriate alternate wording. GitHub now @@ -74,8 +74,8 @@ the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -#. **Were ``What's New in Python`` (in ``Doc/whatsnew/``) and - ``Misc/NEWS.d/next``updated?** If the change is particularly interesting +#. **Were What's New in Python (in Doc/whatsnew/) and + Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added @@ -169,8 +169,8 @@ Python repositories, so you need to be careful with your workflow: You can also push these branches to a **separate** public repository for maintenance work before it is integrated into the main repository. -* **You should not commit directly into the ``master`` branch, or any of the - maintenance branches (currently ``3.9`` and ``3.8``).** You should commit +* **You should not commit directly into the master branch, or any of the + maintenance branches (currently 3.9 and 3.8).** You should commit against your own feature branch, and then create a pull request. * **For a small change, you can make a quick edit through the GitHub web UI.** From 5be3269195964c5b81b482e64f70c9f6727df3f3 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:40:29 -0800 Subject: [PATCH 07/42] Allcaps for NEWS --- committing.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/committing.rst b/committing.rst index 0ff022b700..e3f3a3e53f 100644 --- a/committing.rst +++ b/committing.rst @@ -80,9 +80,9 @@ the public source tree. Ask yourself the following questions: backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect only documentation generally do not require - a news entry. (See the following section for more information.) + a NEWS entry. (See the following section for more information.) -Updating News and What's New in Python +Updating NEWS and What's New in Python -------------------------------------- Almost all changes made to the code base deserve an entry in ``Misc/NEWS.d``. @@ -90,12 +90,12 @@ If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect documentation only generally do not require -a news entry. +a NEWS entry. There are two notable exceptions to this general principle, and they both relate to changes that: -* Already have a news entry +* Already have a NEWS entry * Have not yet been included in any formal release (including alpha and beta releases) @@ -107,18 +107,18 @@ These are the two exceptions: an alpha and then cut prior to the first beta). #. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original news entry remains valid**, then no additional + change and the original NEWS entry remains valid**, then no additional entry is needed. If a change needs an entry in ``What's New in Python``, then it very likely *not* suitable for including in a maintenance release. -News entries go into the ``Misc/NEWS.d`` directory as individual files. The -news entry can be created by using `blurb-it `_, +NEWS entries go into the ``Misc/NEWS.d`` directory as individual files. The +NEWS entry can be created by using `blurb-it `_, or the `blurb `_ tool and its ``blurb add`` command. -If you are unable to use the tool, then you can create the news entry file +If you are unable to use the tool, then you can create the NEWS entry file manually. The ``Misc/NEWS.d`` directory contains a sub-directory named ``next``, which contains various sub-directories representing classifications for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating From ff18318cff00215d99940ad0f094fd3686f2ddd8 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:41:59 -0800 Subject: [PATCH 08/42] Sentence case for subheadings --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index e3f3a3e53f..1f2ffeaf52 100644 --- a/committing.rst +++ b/committing.rst @@ -8,7 +8,7 @@ Accepting Pull Requests This page is a step-by-step guide for core developers who need to assess, merge, and possibly backport a pull request on the main repository. -Assessing a Pull Request +Assessing a pull request -------------- Before you can accept a PR, you need to make sure that it is ready to enter From 1f7687ca466fb761cd42c60143a3d0cb4c467a92 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:45:29 -0800 Subject: [PATCH 09/42] Allcaps NEWS --- committing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index 1f2ffeaf52..dcf3be56bb 100644 --- a/committing.rst +++ b/committing.rst @@ -137,11 +137,11 @@ to the standard library). The file name itself should be in the format As a result, a file name can look something like ``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.bpo-12345.Yl4gI2.rst``. -The contents of a news file should be valid reStructuredText. An 80 character +The contents of a NEWS file should be valid reStructuredText. An 80 character column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a news +:ref:`inline markups ` too. Here is an example of a NEWS entry:: Fix warning message when :func:`os.chdir` fails inside From 2b91e104e9261c87f4e885e83742140250cf7623 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:47:14 -0800 Subject: [PATCH 10/42] Remove inconsistent bold --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index dcf3be56bb..96122a8509 100644 --- a/committing.rst +++ b/committing.rst @@ -175,7 +175,7 @@ Python repositories, so you need to be careful with your workflow: * **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will - create a new branch in the **main** CPython repo rather than in your fork. + create a new branch in the main CPython repo rather than in your fork. Delete this newly created branch after it has been merged into the ``master`` branch or any of the maintenance branches. To keep the CPython repo tidy, remove the new branch within a few days. From ef292e095f079a36858e29bc25f2ed434ff5f269 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:51:09 -0800 Subject: [PATCH 11/42] Reader-focused phrasing --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 96122a8509..27eded18f8 100644 --- a/committing.rst +++ b/committing.rst @@ -222,7 +222,7 @@ hashes and their first line of the commit, use the following command:: .. _backport-pr-title: -Prefix the backport pull request with the branch, and reference the pull request +You can prefix the backport pull request with the branch, and reference the pull request number from ``master``. Here is an example:: [3.9] bpo-12345: Fix the Spam Module (GH-NNNN) From e6b848b2e72e974d7e666849d2c9a457d593a9a9 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Wed, 23 Dec 2020 15:52:31 -0800 Subject: [PATCH 12/42] Verb tense --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 27eded18f8..96bf418f34 100644 --- a/committing.rst +++ b/committing.rst @@ -243,7 +243,7 @@ Reverting a merged pull request To revert a merged pull request, press the ``Revert`` button at the bottom of the pull request. That will bring up the page to create a new pull request where -the commit can be reverted. It also creates a new branch on the main CPython +the commit can be reverted. It will also create a new branch on the main CPython repository. Delete the branch once the pull request has been merged. Always include the reason for reverting the commit to help others understand From f4e9e83ea3cf97607ca04a360f84bfcad78ce327 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 09:13:58 -0800 Subject: [PATCH 13/42] Add empty lines between list items: learn rst --- committing.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/committing.rst b/committing.rst index 96bf418f34..b42779e008 100644 --- a/committing.rst +++ b/committing.rst @@ -18,25 +18,31 @@ the public source tree. Ask yourself the following questions: only branch that receives new features is ``master``, the in-development branch. + #. **Are there comments on the PR?** Look for explanations about whether the code coverage increased or stayed the same. + #. **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 PR, publish patches on the `issue tracker `_, or create a public fork of the repository. + #. **Does the check on the PR show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. + #. **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. + #. **Do the changes meet the requirements of the patch checklist?** :ref:`Run patchcheck ` to perform a quick confidence check on the changes. + #. **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the @@ -44,9 +50,11 @@ the public source tree. Ask yourself the following questions: cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. + #. **Were configure and pyconfig.h.in regenerated?** Regnenerate them if necessary. + #. **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core @@ -56,6 +64,7 @@ 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 PR have a label 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 @@ -65,6 +74,7 @@ the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to: contributors@python.org. + #. **Was the contributor added to Misc/ACKS?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial @@ -74,6 +84,7 @@ the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. + #. **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or @@ -82,6 +93,7 @@ the public source tree. Ask yourself the following questions: as well. Changes that affect only documentation generally do not require a NEWS entry. (See the following section for more information.) + Updating NEWS and What's New in Python -------------------------------------- From 39d40d8a56d20ca02f686911e90cd2b0658f13f0 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 09:15:00 -0800 Subject: [PATCH 14/42] Add whitespace: learn rst --- committing.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/committing.rst b/committing.rst index b42779e008..dabe23fa02 100644 --- a/committing.rst +++ b/committing.rst @@ -14,6 +14,7 @@ Assessing a pull request Before you can accept a PR, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: + #. **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. @@ -94,6 +95,7 @@ the public source tree. Ask yourself the following questions: a NEWS entry. (See the following section for more information.) + Updating NEWS and What's New in Python -------------------------------------- From ed2dc390e085d6100090214da5d1d277e6ae25bd Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 09:17:00 -0800 Subject: [PATCH 15/42] Remove double empty lines between list items --- committing.rst | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/committing.rst b/committing.rst index dabe23fa02..9533e7f74b 100644 --- a/committing.rst +++ b/committing.rst @@ -14,36 +14,29 @@ Assessing a pull request Before you can accept a PR, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: - #. **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. - - + #. **Are there comments on the PR?** Look for explanations about whether the code coverage increased or stayed the same. - #. **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 PR, publish patches on the `issue tracker `_, or create a public fork of the repository. - #. **Does the check on the PR show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. - #. **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. - #. **Do the changes meet the requirements of the patch checklist?** :ref:`Run patchcheck ` to perform a quick confidence check on the changes. - #. **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the @@ -51,11 +44,9 @@ the public source tree. Ask yourself the following questions: cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. - #. **Were configure and pyconfig.h.in regenerated?** Regnenerate them if necessary. - #. **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core @@ -65,7 +56,6 @@ 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 PR have a label 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 @@ -75,7 +65,6 @@ the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to: contributors@python.org. - #. **Was the contributor added to Misc/ACKS?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial @@ -85,7 +74,6 @@ the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. - #. **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or @@ -95,7 +83,6 @@ the public source tree. Ask yourself the following questions: a NEWS entry. (See the following section for more information.) - Updating NEWS and What's New in Python -------------------------------------- From 46346973df95da448ce108ec5f97b5f1e32d4814 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 09:19:15 -0800 Subject: [PATCH 16/42] Replace "PR" with "pull request" --- committing.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/committing.rst b/committing.rst index 9533e7f74b..a91b28e4b1 100644 --- a/committing.rst +++ b/committing.rst @@ -11,22 +11,22 @@ merge, and possibly backport a pull request on the main repository. Assessing a pull request -------------- -Before you can accept a PR, you need to make sure that it is ready to enter +Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: #. **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. -#. **Are there comments on the PR?** Look for explanations about whether +#. **Are there comments on the pull request?** Look for explanations about whether the code coverage increased or stayed the same. #. **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 PR, + 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. -#. **Does the check on the PR show that the test suite passes?** :ref:`Run the +#. **Does the check on the pull request show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. @@ -56,7 +56,7 @@ 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 PR have a label indicating that the submitter has signed the +#. **Does the pull request have a label 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 associated with it (e.g. fixing a spelling mistake in From 64de2c8e9a437fb9b6a720c652bc24c157ca8947 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 10:18:18 -0800 Subject: [PATCH 17/42] Line length and spacing --- committing.rst | 181 +++++++++++++++++++++++++++---------------------- 1 file changed, 100 insertions(+), 81 deletions(-) diff --git a/committing.rst b/committing.rst index a91b28e4b1..31749fd450 100644 --- a/committing.rst +++ b/committing.rst @@ -5,84 +5,98 @@ Accepting Pull Requests .. highlight:: none -This page is a step-by-step guide for core developers who need to assess, +This page is a step-by-step guide for core developers who need to assess, merge, and possibly backport a pull request on the main repository. Assessing a pull request -------------- -Before you can accept a pull request, you need to make sure that it is ready to enter -the public source tree. Ask yourself the following questions: +Before you can accept a pull request, you need to make sure that it is ready +to enter the public source tree. Ask yourself the following questions: -#. **Was the pull request first made against the master branch?** The - only branch that receives new features is ``master``, the in-development + +#. **Was the pull request first made against the master branch?** The + only branch that receives new features is ``master``, the in-development branch. - -#. **Are there comments on the pull request?** Look for explanations about whether - the code coverage increased or stayed the same. -#. **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. -#. **Does the check on the pull request show that the test suite passes?** :ref:`Run the - entire test suite ` to ensure that it passes. Running a single - test is not enough since the changes may have unforeseen effects on other - tests or library modules. +#. **Are there comments on the pull request?** Look for explanations about + whether the code coverage increased or stayed the same. + + +#. **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. + + +#. **Does the check on the pull request show that the test suite passes?** + :ref:`Run the entire test suite ` to ensure that it passes. + Running a single test is not enough since the changes may have unforeseen + effects on other tests or library modules. + #. **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. -#. **Do the changes meet the requirements of the patch checklist?** :ref:`Run - patchcheck ` to perform a quick confidence check on the changes. -#. **Does the patch break backwards-compatibility without a strong +#. **Do the changes meet the requirements of the patch checklist?** + :ref:`Run patchcheck ` to perform a quick confidence + check on the changes. + + +#. **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the - semantics, then there needs to be a strong reason, because it will + semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. - -#. **Were configure and pyconfig.h.in regenerated?** + + +#. **Were configure and pyconfig.h.in regenerated?** Regnenerate them if necessary. + #. **Were appropriate labels added to signify necessary backporting of the - pull request?** If it is determined that a pull request needs to be - backported into one or more of the maintenance branches, then a core - developer can apply the label ``needs backport to X.Y`` to the pull + pull request?** If it is determined that a pull request needs to be + backported into one or more of the maintenance branches, then a core + developer can apply the label ``needs backport to X.Y`` to the pull request. Once the backport pull request has been created, remove the - ``needs backport to X.Y`` label from the original pull request. (Only - core developers and members of the `Python Triage Team`_ can apply + ``needs backport to X.Y`` label from the original pull request. (Only + 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?** Make sure that the contributor has signed a `Contributor Licensing - Agreement`_ (CLA), unless their change has no possible intellectual - property associated with it (e.g. fixing a spelling mistake in - documentation). To check if a contributor’s CLA has been received, go - to `Check Python CLA `_ and - put in their GitHub username. For further questions about the CLA + +#. **Does the pull request have a label 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 associated with it (e.g. fixing a spelling mistake + in documentation). To check if a contributor’s CLA has been received, go + to `Check Python CLA `_ and + put in their GitHub username. For further questions about the CLA process, write to: contributors@python.org. -#. **Was the contributor added to Misc/ACKS?** Make sure that - the patch is attributed correctly with the contributor's name in + +#. **Was the contributor added to Misc/ACKS?** Make sure that + the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial - patch by " is an appropriate alternate wording. GitHub now - supports `multiple authors + patch by " is an appropriate alternate wording. GitHub now + supports `multiple authors `_ - in a commit. Add ``Co-authored-by: name `` at the end + in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -#. **Were What's New in Python (in Doc/whatsnew/) and - Misc/NEWS.d/next updated?** If the change is particularly interesting - for end users (e.g. new features, significant improvements, or - backwards-incompatible changes), then an entry in the + +#. **Were What's New in Python (in Doc/whatsnew/) and + Misc/NEWS.d/next updated?** If the change is particularly interesting + for end users (e.g. new features, significant improvements, or + backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect only documentation generally do not require a NEWS entry. (See the following section for more information.) + Updating NEWS and What's New in Python -------------------------------------- @@ -97,21 +111,21 @@ There are two notable exceptions to this general principle, and they both relate to changes that: * Already have a NEWS entry -* Have not yet been included in any formal release (including alpha +* Have not yet been included in any formal release (including alpha and beta releases) These are the two exceptions: -#. **If a change is reverted prior to release**, then the corresponding - entry is simply removed. Otherwise, a new entry must be added noting - that the change has been reverted (e.g. when a feature is released in +#. **If a change is reverted prior to release**, then the corresponding + entry is simply removed. Otherwise, a new entry must be added noting + that the change has been reverted (e.g. when a feature is released in an alpha and then cut prior to the first beta). -#. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original NEWS entry remains valid**, then no additional +#. **If a change is a fix (or other adjustment) to an earlier unreleased + change and the original NEWS entry remains valid**, then no additional entry is needed. -If a change needs an entry in ``What's New in Python``, then it very +If a change needs an entry in ``What's New in Python``, then it very likely *not* suitable for including in a maintenance release. NEWS entries go into the ``Misc/NEWS.d`` directory as individual files. The @@ -119,10 +133,10 @@ NEWS entry can be created by using `blurb-it `_ or the `blurb `_ tool and its ``blurb add`` command. -If you are unable to use the tool, then you can create the NEWS entry file -manually. The ``Misc/NEWS.d`` directory contains a sub-directory named -``next``, which contains various sub-directories representing classifications -for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating +If you are unable to use the tool, then you can create the NEWS entry file +manually. The ``Misc/NEWS.d`` directory contains a sub-directory named +``next``, which contains various sub-directories representing classifications +for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the standard library). The file name itself should be in the format ``.bpo-..rst``: @@ -132,7 +146,7 @@ to the standard library). The file name itself should be in the format for ``bpo-12345``). * ```` is a unique string to guarantee that the file name is unique across branches (e.g. ``Yl4gI2``). (It is typically six characters - long, but it can be any length of letters and numbers. Its uniqueness + long, but it can be any length of letters and numbers. Its uniqueness can be satisfied by typing random characters on your keyboard.) As a result, a file name can look something like @@ -142,14 +156,14 @@ The contents of a NEWS file should be valid reStructuredText. An 80 character column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a NEWS +:ref:`inline markups ` too. Here is an example of a NEWS entry:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. The inline Sphinx roles like ``:func:`` can be used help readers -find more information. You can build html and verify that the +find more information. You can build html and verify that the link target is appropriate by using :ref:`make html `. While Sphinx roles can be beneficial to readers, they are not required. @@ -162,27 +176,31 @@ Working with Git_ .. seealso:: :ref:`gitbootcamp` -As a core developer, you have the ability to push changes to the official +As a core developer, you have the ability to push changes to the official Python repositories, so you need to be careful with your workflow: -* **You should not push new branches to the main repository.** You can - still use them in the fork that you use for the development of patches. - You can also push these branches to a **separate** public repository + +* **You should not push new branches to the main repository.** You can + still use them in the fork that you use for the development of patches. + You can also push these branches to a separate public repository for maintenance work before it is integrated into the main repository. + * **You should not commit directly into the master branch, or any of the - maintenance branches (currently 3.9 and 3.8).** You should commit + maintenance branches (currently 3.9 and 3.8).** You should commit against your own feature branch, and then create a pull request. + * **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will - create a new branch in the main CPython repo rather than in your fork. - Delete this newly created branch after it has been merged into the + create a new branch in the main CPython repo rather than in your fork. + Delete this newly created branch after it has been merged into the ``master`` branch or any of the maintenance branches. To keep the CPython repo tidy, remove the new branch within a few days. -Keep a fork of the main repository, since it will allow you to revert all -local changes (even committed ones) if you're not happy with your local + +Keep a fork of the main repository, since it will allow you to revert all +local changes (even committed ones) if you're not happy with your local clone. @@ -194,8 +212,8 @@ clone. Seeing active branches '''''''''''''''''''''' -If you use ``git branch``, then you will see a :ref:`list of branches -`. The only branch that receives new features is +If you use ``git branch``, then you will see a :ref:`list of branches +`. The only branch that receives new features is ``master``, the in-development branch. The other branches receive only bug fixes or security fixes. @@ -216,24 +234,24 @@ backporting it themselves, using the backport generated by cherry_picker.py_ as a starting point. You can get the commit hash from the original pull request, or you can use -``git log`` on the ``master`` branch. To display the 10 most recent commit +``git log`` on the ``master`` branch. To display the 10 most recent commit hashes and their first line of the commit, use the following command:: git log -10 --oneline .. _backport-pr-title: -You can prefix the backport pull request with the branch, and reference the pull request -number from ``master``. Here is an example:: +You can prefix the backport pull request with the branch, and reference +the pull request number from ``master``. Here is an example:: [3.9] bpo-12345: Fix the Spam Module (GH-NNNN) Note that cherry_picker.py_ adds the branch prefix automatically. Once the backport pull request has been created, remove the -``needs backport to X.Y`` label from the original pull request. (Only core -developers and members of the `Python Triage Team`_ can apply labels to GitHub -pull requests). +``needs backport to X.Y`` label from the original pull request. (Only +core developers and members of the `Python Triage Team`_ can apply +labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/cherry-picker .. _`Python Triage Team`: https://devguide.python.org/triaging/#python-triage-team @@ -242,14 +260,15 @@ pull requests). Reverting a merged pull request ''''''''''''''''''''''''''''''' -To revert a merged pull request, press the ``Revert`` button at the bottom of -the pull request. That will bring up the page to create a new pull request where -the commit can be reverted. It will also create a new branch on the main CPython -repository. Delete the branch once the pull request has been merged. +To revert a merged pull request, press the ``Revert`` button at the +bottom of the pull request. That will bring up the page to create a +new pull request where the commit can be reverted. It will also create +a new branch on the main CPython repository. Delete the branch once +the pull request has been merged. -Always include the reason for reverting the commit to help others understand -why it was done. The reason should be included as part of the commit message. -Here is an example:: +Always include the reason for reverting the commit to help others +understand why it was done. The reason should be included as part of +the commit message. Here is an example:: Revert bpo-NNNN: Fix Spam Module (GH-111) From cfae6737c5f38656c72e53b14394108aa94f4ff9 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 10:30:33 -0800 Subject: [PATCH 18/42] Typo & consistent terminology --- committing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index 31749fd450..38e74e8a42 100644 --- a/committing.rst +++ b/committing.rst @@ -53,8 +53,8 @@ to enter the public source tree. Ask yourself the following questions: is worth it, then ask on python-dev. -#. **Were configure and pyconfig.h.in regenerated?** - Regnenerate them if necessary. +#. **Were configure and pyconfig.h.in regenerated?** Regenerate them + if necessary. #. **Were appropriate labels added to signify necessary backporting of the @@ -193,10 +193,10 @@ Python repositories, so you need to be careful with your workflow: * **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will - create a new branch in the main CPython repo rather than in your fork. + create a new branch in the main CPython repository rather than in your fork. Delete this newly created branch after it has been merged into the ``master`` branch or any of the maintenance branches. To keep the CPython - repo tidy, remove the new branch within a few days. + repository tidy, remove the new branch within a few days. Keep a fork of the main repository, since it will allow you to revert all From 922184290a21c66f2f6294fc4b99b7a3394c44dc Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 10:49:36 -0800 Subject: [PATCH 19/42] Light proofread --- committing.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/committing.rst b/committing.rst index 38e74e8a42..766a2a7a5a 100644 --- a/committing.rst +++ b/committing.rst @@ -74,7 +74,7 @@ to enter the public source tree. Ask yourself the following questions: in documentation). To check if a contributor’s CLA has been received, go to `Check Python CLA `_ and put in their GitHub username. For further questions about the CLA - process, write to: contributors@python.org. + process, write to contributors@python.org. #. **Was the contributor added to Misc/ACKS?** Make sure that @@ -126,7 +126,7 @@ These are the two exceptions: entry is needed. If a change needs an entry in ``What's New in Python``, then it very -likely *not* suitable for including in a maintenance release. +likely not suitable for including in a maintenance release. NEWS entries go into the ``Misc/NEWS.d`` directory as individual files. The NEWS entry can be created by using `blurb-it `_, @@ -140,14 +140,14 @@ for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the standard library). The file name itself should be in the format ``.bpo-..rst``: -* ```` is today's date joined with a ``-`` to the current - time, in ``YYYY-MM-DD-hh-mm-ss`` format (e.g. ``2017-05-27-16-46-23``). +* ```` is today's date joined with a hyphen (``-``) to the current + time, in the ``YYYY-MM-DD-hh-mm-ss`` format (e.g. ``2017-05-27-16-46-23``). * ```` is the issue number the change is for (e.g. ``12345`` for ``bpo-12345``). * ```` is a unique string to guarantee that the file name is - unique across branches (e.g. ``Yl4gI2``). (It is typically six characters + unique across branches (e.g. ``Yl4gI2``). It is typically six characters long, but it can be any length of letters and numbers. Its uniqueness - can be satisfied by typing random characters on your keyboard.) + can be satisfied by typing random characters on your keyboard. As a result, a file name can look something like ``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.bpo-12345.Yl4gI2.rst``. From 25a885abba11ec677974087c31442e91e8d20cf5 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 12:34:39 -0800 Subject: [PATCH 20/42] Made line under heading long enough --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 766a2a7a5a..dc2d16b88a 100644 --- a/committing.rst +++ b/committing.rst @@ -9,7 +9,7 @@ This page is a step-by-step guide for core developers who need to assess, merge, and possibly backport a pull request on the main repository. Assessing a pull request --------------- +------------------------ Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: From 31ed26d554d4ce5b34a8b83b8e36fd7d8dfc7cd9 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 12:45:16 -0800 Subject: [PATCH 21/42] Add link to CLA --- committing.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/committing.rst b/committing.rst index dc2d16b88a..28405df815 100644 --- a/committing.rst +++ b/committing.rst @@ -69,9 +69,10 @@ to enter the public source tree. Ask yourself the following questions: #. **Does the pull request have a label 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 associated with it (e.g. fixing a spelling mistake - in documentation). To check if a contributor’s CLA has been received, go + Licensing Agreement `_ + (CLA), unless their change has no possible intellectual property + associated with it (e.g. fixing a spelling mistake in documentation). + To check if a contributor’s CLA has been received, go to `Check Python CLA `_ and put in their GitHub username. For further questions about the CLA process, write to contributors@python.org. From e8177215c30e0cfe6feb7f4a478c2ea4c905f5f1 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:04:04 -0800 Subject: [PATCH 22/42] Changed ordered list to unordered list --- committing.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/committing.rst b/committing.rst index 28405df815..1a5d312c75 100644 --- a/committing.rst +++ b/committing.rst @@ -15,37 +15,37 @@ Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: -#. **Was the pull request first made against the master branch?** The +* **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. -#. **Are there comments on the pull request?** Look for explanations about +* **Are there comments on the pull request?** Look for explanations about whether the code coverage increased or stayed the same. -#. **Are the changes acceptable?** If you want to share your work-in-progress +* **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. -#. **Does the check on the pull request show that the test suite passes?** +* **Does the check on the pull request show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. -#. **Is the patch in a good state?** Check :ref:`patch` and +* **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. -#. **Do the changes meet the requirements of the patch checklist?** +* **Do the changes meet the requirements of the patch checklist?** :ref:`Run patchcheck ` to perform a quick confidence check on the changes. -#. **Does the patch break backwards-compatibility without a strong +* **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will @@ -53,11 +53,11 @@ to enter the public source tree. Ask yourself the following questions: is worth it, then ask on python-dev. -#. **Were configure and pyconfig.h.in regenerated?** Regenerate them +* **Were configure and pyconfig.h.in regenerated?** Regenerate them if necessary. -#. **Were appropriate labels added to signify necessary backporting of the +* **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core developer can apply the label ``needs backport to X.Y`` to the pull @@ -67,7 +67,7 @@ to enter the public source tree. Ask yourself the following questions: labels to GitHub pull requests). -#. **Does the pull request have a label indicating that the submitter has +* **Does the pull request have a label 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 @@ -78,7 +78,7 @@ to enter the public source tree. Ask yourself the following questions: process, write to contributors@python.org. -#. **Was the contributor added to Misc/ACKS?** Make sure that +* **Was the contributor added to Misc/ACKS?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial patch by " is an appropriate alternate wording. GitHub now @@ -88,7 +88,7 @@ to enter the public source tree. Ask yourself the following questions: of the commit message. -#. **Were What's New in Python (in Doc/whatsnew/) and +* **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the From 12096802a121e5c7808d6d3a234c294de40f2295 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:14:15 -0800 Subject: [PATCH 23/42] Change list formatting --- committing.rst | 68 ++++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/committing.rst b/committing.rst index 1a5d312c75..3cb97d5c57 100644 --- a/committing.rst +++ b/committing.rst @@ -15,29 +15,32 @@ Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: -* **Was the pull request first made against the master branch?** The - only branch that receives new features is ``master``, the in-development - branch. +* **Was the pull request first made against the master branch?** + The only branch that receives new features is ``master``, the + in-development branch. -* **Are there comments on the pull request?** Look for explanations about - whether the code coverage increased or stayed the same. +* **Are there comments on the pull request?** + Look for explanations about whether the code coverage increased or + stayed the same. -* **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. +* **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. -* **Does the check on the pull request show that the test suite passes?** +* **Does the check on the pull request show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. -* **Is the patch in a good state?** Check :ref:`patch` and - :ref:`helptriage` to review what is expected of a patch. +* **Is the patch in a good state?** + Check :ref:`patch` and :ref:`helptriage` to review what is expected of + a patch. * **Do the changes meet the requirements of the patch checklist?** @@ -45,20 +48,20 @@ to enter the public source tree. Ask yourself the following questions: check on the changes. -* **Does the patch break backwards-compatibility without a strong - reason?** :ref:`Run the entire test suite ` to - make sure that everything still passes. If there is a change to the - semantics, then there needs to be a strong reason, because it will - cause some peoples' code to break. If you are unsure if the breakage - is worth it, then ask on python-dev. +* **Does the patch break backwards-compatibility without a strong reason?** + :ref:`Run the entire test suite ` to make sure that everything + still passes. If there is a change to the semantics, then there needs to + be a strong reason, because it will cause some peoples' code to break. + If you are unsure if the breakage is worth it, then ask on python-dev. -* **Were configure and pyconfig.h.in regenerated?** Regenerate them - if necessary. +* **Were configure and pyconfig.h.in regenerated?** + Regenerate them if necessary. * **Were appropriate labels added to signify necessary backporting of the - pull request?** If it is determined that a pull request needs to be + pull request?** + If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core developer can apply the label ``needs backport to X.Y`` to the pull request. Once the backport pull request has been created, remove the @@ -68,7 +71,8 @@ to enter the public source tree. Ask yourself the following questions: * **Does the pull request have a label indicating that the submitter has - signed the CLA?** Make sure that the contributor has signed a `Contributor + signed the CLA?** + Make sure that the contributor has signed a `Contributor Licensing Agreement `_ (CLA), unless their change has no possible intellectual property associated with it (e.g. fixing a spelling mistake in documentation). @@ -78,10 +82,10 @@ to enter the public source tree. Ask yourself the following questions: process, write to contributors@python.org. -* **Was the contributor added to Misc/ACKS?** Make sure that - the patch is attributed correctly with the contributor's name in - ``Misc/ACKS``. If the patch has been heavily modified, then "Initial - patch by " is an appropriate alternate wording. GitHub now +* **Was the contributor added to Misc/ACKS?** + Make sure that the patch is attributed correctly with the contributor's + name in ``Misc/ACKS``. If the patch has been heavily modified, then + "Initial patch by " is an appropriate alternate wording. GitHub now supports `multiple authors `_ in a commit. Add ``Co-authored-by: name `` at the end @@ -89,12 +93,12 @@ to enter the public source tree. Ask yourself the following questions: * **Were What's New in Python (in Doc/whatsnew/) and - Misc/NEWS.d/next updated?** If the change is particularly interesting - for end users (e.g. new features, significant improvements, or - backwards-incompatible changes), then an entry in the - ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added - as well. Changes that affect only documentation generally do not require - a NEWS entry. (See the following section for more information.) + Misc/NEWS.d/next updated?** + If the change is particularly interesting for end users (e.g. new features, + significant improvements, or backwards-incompatible changes), then an + entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should + be added as well. Changes that affect only documentation generally do not + require a NEWS entry. (See the following section for more information.) From a79e2d17449150b33224663724abbd2d27ed7f68 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:21:35 -0800 Subject: [PATCH 24/42] Removed empty lines in list --- committing.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/committing.rst b/committing.rst index 3cb97d5c57..c0dbc25f58 100644 --- a/committing.rst +++ b/committing.rst @@ -14,51 +14,42 @@ Assessing a pull request Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: - * **Was the pull request first made against the master branch?** The only branch that receives new features is ``master``, the in-development branch. - * **Are there comments on the pull request?** Look for explanations about whether the code coverage increased or stayed the same. - * **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. - * **Does the check on the pull request show that the test suite passes?** :ref:`Run the entire test suite ` to ensure that it passes. Running a single test is not enough since the changes may have unforeseen effects on other tests or library modules. - * **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. - * **Do the changes meet the requirements of the patch checklist?** :ref:`Run patchcheck ` to perform a quick confidence check on the changes. - * **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. - * **Were configure and pyconfig.h.in regenerated?** Regenerate them if necessary. - * **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be @@ -69,7 +60,6 @@ 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?** Make sure that the contributor has signed a `Contributor @@ -81,7 +71,6 @@ to enter the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to contributors@python.org. - * **Was the contributor added to Misc/ACKS?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then @@ -91,7 +80,6 @@ to enter the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. - * **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, @@ -101,7 +89,6 @@ to enter the public source tree. Ask yourself the following questions: require a NEWS entry. (See the following section for more information.) - Updating NEWS and What's New in Python -------------------------------------- From d543c519a9226846fe2821f2a321067fbc660baf Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:28:19 -0800 Subject: [PATCH 25/42] Changed bolding --- committing.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/committing.rst b/committing.rst index c0dbc25f58..d3a191eca1 100644 --- a/committing.rst +++ b/committing.rst @@ -50,8 +50,8 @@ to enter the public source tree. Ask yourself the following questions: * **Were configure and pyconfig.h.in regenerated?** Regenerate them if necessary. -* **Were appropriate labels added to signify necessary backporting of the - pull request?** +* **Were appropriate labels added to signify necessary backporting of the** + **pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core developer can apply the label ``needs backport to X.Y`` to the pull @@ -60,8 +60,8 @@ 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 have a label 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 @@ -80,8 +80,7 @@ to enter the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -* **Were What's New in Python (in Doc/whatsnew/) and - Misc/NEWS.d/next updated?** +* **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From dc087d38153586c9734007348ef8a974c64c87ed Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:34:15 -0800 Subject: [PATCH 26/42] Changed line length for list formatting --- committing.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index d3a191eca1..7d5e50edbc 100644 --- a/committing.rst +++ b/committing.rst @@ -50,8 +50,7 @@ to enter the public source tree. Ask yourself the following questions: * **Were configure and pyconfig.h.in regenerated?** Regenerate them if necessary. -* **Were appropriate labels added to signify necessary backporting of the** - **pull request?** +* **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core developer can apply the label ``needs backport to X.Y`` to the pull @@ -60,8 +59,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 have a label 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 From da180f8e003a52d74011c9f41f40e6718cdbce59 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:40:13 -0800 Subject: [PATCH 27/42] Changed word order for clarity without monospace --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 7d5e50edbc..059a5c5291 100644 --- a/committing.rst +++ b/committing.rst @@ -47,7 +47,7 @@ to enter the public source tree. Ask yourself the following questions: be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. -* **Were configure and pyconfig.h.in regenerated?** +* **Were pyconfig.h.in and configure regenerated?** Regenerate them if necessary. * **Were appropriate labels added to signify necessary backporting of the pull request?** From 567aa816007eb161022ec89fbba48d2283a7c71e Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:50:37 -0800 Subject: [PATCH 28/42] Added monospace to bold sections --- committing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/committing.rst b/committing.rst index 059a5c5291..153adccb46 100644 --- a/committing.rst +++ b/committing.rst @@ -47,7 +47,7 @@ to enter the public source tree. Ask yourself the following questions: be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. -* **Were pyconfig.h.in and configure regenerated?** +* **Were** ``pyconfig.h.in`` **and** ``configure`` **regenerated?** Regenerate them if necessary. * **Were appropriate labels added to signify necessary backporting of the pull request?** @@ -69,7 +69,7 @@ to enter the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to contributors@python.org. -* **Was the contributor added to Misc/ACKS?** +* **Was the contributor added to** ``Misc/ACKS``**?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial patch by " is an appropriate alternate wording. GitHub now @@ -78,7 +78,7 @@ to enter the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -* **Were What's New in Python (in Doc/whatsnew/) and Misc/NEWS.d/next updated?** +* **Were What's New in Python (in** ``Doc/whatsnew/``**) and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From 2271326d269825941cec5638322735c33de20a72 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 13:54:25 -0800 Subject: [PATCH 29/42] Font formatting --- committing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index 153adccb46..9e6989d027 100644 --- a/committing.rst +++ b/committing.rst @@ -69,7 +69,7 @@ to enter the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to contributors@python.org. -* **Was the contributor added to** ``Misc/ACKS``**?** +* **Was the contributor added to** ``Misc/ACKS`` **?** Make sure that the patch is attributed correctly with the contributor's name in ``Misc/ACKS``. If the patch has been heavily modified, then "Initial patch by " is an appropriate alternate wording. GitHub now @@ -78,7 +78,7 @@ to enter the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -* **Were What's New in Python (in** ``Doc/whatsnew/``**) and** ``Misc/NEWS.d/next`` **updated?** +* **Were What's New in Python (in** ``Doc/whatsnew/`` **) and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From 623cea44921a867209b53f6f662d75fa9aca9085 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 14:02:37 -0800 Subject: [PATCH 30/42] Removed redundancy --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 9e6989d027..35c542c5ce 100644 --- a/committing.rst +++ b/committing.rst @@ -78,7 +78,7 @@ to enter the public source tree. Ask yourself the following questions: in a commit. Add ``Co-authored-by: name `` at the end of the commit message. -* **Were What's New in Python (in** ``Doc/whatsnew/`` **) and** ``Misc/NEWS.d/next`` **updated?** +* **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From 10e28fc1b04efac5fd85bf0edd6ad5e2705d1529 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 14:07:57 -0800 Subject: [PATCH 31/42] Monospace NEWS, clean double empty lines --- committing.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/committing.rst b/committing.rst index 35c542c5ce..1ac53088f4 100644 --- a/committing.rst +++ b/committing.rst @@ -83,7 +83,7 @@ to enter the public source tree. Ask yourself the following questions: significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect only documentation generally do not - require a NEWS entry. (See the following section for more information.) + require a ``NEWS`` entry. (See the following section for more information.) Updating NEWS and What's New in Python @@ -94,12 +94,12 @@ If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect documentation only generally do not require -a NEWS entry. +a ``NEWS`` entry. There are two notable exceptions to this general principle, and they both relate to changes that: -* Already have a NEWS entry +* Already have a ``NEWS`` entry * Have not yet been included in any formal release (including alpha and beta releases) @@ -111,18 +111,18 @@ These are the two exceptions: an alpha and then cut prior to the first beta). #. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original NEWS entry remains valid**, then no additional + change and the original ``NEWS`` entry remains valid**, then no additional entry is needed. If a change needs an entry in ``What's New in Python``, then it very likely not suitable for including in a maintenance release. -NEWS entries go into the ``Misc/NEWS.d`` directory as individual files. The -NEWS entry can be created by using `blurb-it `_, +``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The +``NEWS`` entry can be created by using `blurb-it `_, or the `blurb `_ tool and its ``blurb add`` command. -If you are unable to use the tool, then you can create the NEWS entry file +If you are unable to use the tool, then you can create the ``NEWS`` entry file manually. The ``Misc/NEWS.d`` directory contains a sub-directory named ``next``, which contains various sub-directories representing classifications for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating @@ -141,7 +141,7 @@ to the standard library). The file name itself should be in the format As a result, a file name can look something like ``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.bpo-12345.Yl4gI2.rst``. -The contents of a NEWS file should be valid reStructuredText. An 80 character +The contents of a ``NEWS`` file should be valid reStructuredText. An 80 character column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue number since it is part of the file name. You can use @@ -168,18 +168,15 @@ Working with Git_ As a core developer, you have the ability to push changes to the official Python repositories, so you need to be careful with your workflow: - * **You should not push new branches to the main repository.** You can still use them in the fork that you use for the development of patches. You can also push these branches to a separate public repository for maintenance work before it is integrated into the main repository. - * **You should not commit directly into the master branch, or any of the maintenance branches (currently 3.9 and 3.8).** You should commit against your own feature branch, and then create a pull request. - * **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will create a new branch in the main CPython repository rather than in your fork. @@ -187,7 +184,6 @@ Python repositories, so you need to be careful with your workflow: ``master`` branch or any of the maintenance branches. To keep the CPython repository tidy, remove the new branch within a few days. - Keep a fork of the main repository, since it will allow you to revert all local changes (even committed ones) if you're not happy with your local clone. From 9caaf03f0698437ed49d6720719b7991cb6e6075 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 14:11:44 -0800 Subject: [PATCH 32/42] Font formatting --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index 1ac53088f4..e176c16da2 100644 --- a/committing.rst +++ b/committing.rst @@ -111,7 +111,7 @@ These are the two exceptions: an alpha and then cut prior to the first beta). #. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original ``NEWS`` entry remains valid**, then no additional + change and the original** ``NEWS`` **entry remains valid**, then no additional entry is needed. If a change needs an entry in ``What's New in Python``, then it very From 9f7ca66d66b525edfa47ee57013efc13783a02f1 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 14:17:53 -0800 Subject: [PATCH 33/42] Spelling & font formatting --- committing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/committing.rst b/committing.rst index e176c16da2..2d84de0e92 100644 --- a/committing.rst +++ b/committing.rst @@ -145,14 +145,14 @@ The contents of a ``NEWS`` file should be valid reStructuredText. An 80 characte column width should be used. There is no indentation or leading marker in the file (e.g. ``-``). There is also no need to start the entry with the issue number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a NEWS +:ref:`inline markups ` too. Here is an example of a ``NEWS`` entry:: Fix warning message when :func:`os.chdir` fails inside :func:`test.support.temp_cwd`. Patch by Chris Jerdonek. The inline Sphinx roles like ``:func:`` can be used help readers -find more information. You can build html and verify that the +find more information. You can build HTML and verify that the link target is appropriate by using :ref:`make html `. While Sphinx roles can be beneficial to readers, they are not required. From 3b530a98c55c6001b760d9c6d94f4c49d0dfd045 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Thu, 24 Dec 2020 14:23:43 -0800 Subject: [PATCH 34/42] Font formatting --- committing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/committing.rst b/committing.rst index 2d84de0e92..5d3ebc851f 100644 --- a/committing.rst +++ b/committing.rst @@ -14,7 +14,7 @@ Assessing a pull request Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: -* **Was the pull request first made against the master branch?** +* **Was the pull request first made against the** ``master`` **branch?** The only branch that receives new features is ``master``, the in-development branch. @@ -173,9 +173,9 @@ Python repositories, so you need to be careful with your workflow: You can also push these branches to a separate public repository for maintenance work before it is integrated into the main repository. -* **You should not commit directly into the master branch, or any of the - maintenance branches (currently 3.9 and 3.8).** You should commit - against your own feature branch, and then create a pull request. +* **You should not commit directly into the** ``master`` **branch, or any of the maintenance branches (currently 3.9 and 3.8).** + You should commit against your own feature branch, and then create a + pull request. * **For a small change, you can make a quick edit through the GitHub web UI.** If you choose to use the web UI, be aware that GitHub will From afb0c74716d0dc95a179333ea441cdaed6d56a46 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Mon, 28 Dec 2020 11:14:29 -0800 Subject: [PATCH 35/42] Added a reference to b.p.o. --- committing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/committing.rst b/committing.rst index 5d3ebc851f..e0954f7713 100644 --- a/committing.rst +++ b/committing.rst @@ -14,6 +14,10 @@ Assessing a pull request Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: +* **Are there ongoing discussions at** `bugs.python.org` **(b.p.o.)?** + Read the linked b.p.o. issue. If there are ongoing discussions, then + we need to find a consensus before we can merge the pull request. + * **Was the pull request first made against the** ``master`` **branch?** The only branch that receives new features is ``master``, the in-development branch. From 6c7cf90126a4ce9cb50f6904fc347d7df5cf1fe6 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Mon, 28 Dec 2020 11:20:30 -0800 Subject: [PATCH 36/42] Fixed monospace --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index e0954f7713..c9ee716d34 100644 --- a/committing.rst +++ b/committing.rst @@ -14,7 +14,7 @@ Assessing a pull request Before you can accept a pull request, you need to make sure that it is ready to enter the public source tree. Ask yourself the following questions: -* **Are there ongoing discussions at** `bugs.python.org` **(b.p.o.)?** +* **Are there ongoing discussions at** ``bugs.python.org`` **(b.p.o.)?** Read the linked b.p.o. issue. If there are ongoing discussions, then we need to find a consensus before we can merge the pull request. From 864c27a70f772b2fb6b40dc2c80a4c890bf9c802 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Mon, 4 Jan 2021 08:41:24 -0800 Subject: [PATCH 37/42] Removed instructions to run patchcheck --- committing.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/committing.rst b/committing.rst index c9ee716d34..ada58405ca 100644 --- a/committing.rst +++ b/committing.rst @@ -41,10 +41,6 @@ to enter the public source tree. Ask yourself the following questions: Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. -* **Do the changes meet the requirements of the patch checklist?** - :ref:`Run patchcheck ` to perform a quick confidence - check on the changes. - * **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to From f4e718aea2b1358dafcd486b98810fa0d9dde55d Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Mon, 4 Jan 2021 21:04:52 -0800 Subject: [PATCH 38/42] Put patchcheck instructions back in --- committing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/committing.rst b/committing.rst index ada58405ca..e6b0e1519a 100644 --- a/committing.rst +++ b/committing.rst @@ -40,6 +40,10 @@ to enter the public source tree. Ask yourself the following questions: * **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. + +* **Do the changes meet the requirements of the patch checklist?** + :ref:`Run patchcheck ` to perform a confidence check and + flag extra whitespace. * **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything From 76aea1908cc7871e5416aa9a5f3e5b054fc4c421 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Sat, 9 Jan 2021 08:38:34 -0800 Subject: [PATCH 39/42] Corrected wording in the reference to b.p.o. Co-authored-by: Brett Cannon --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index e6b0e1519a..775d8c7572 100644 --- a/committing.rst +++ b/committing.rst @@ -16,7 +16,7 @@ to enter the public source tree. Ask yourself the following questions: * **Are there ongoing discussions at** ``bugs.python.org`` **(b.p.o.)?** Read the linked b.p.o. issue. If there are ongoing discussions, then - we need to find a consensus before we can merge the pull request. + we need to have a resolution there before we can merge the pull request. * **Was the pull request first made against the** ``master`` **branch?** The only branch that receives new features is ``master``, the From d1b5acf0964ba6132ada0a71d572e7b09611b74c Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Sun, 10 Jan 2021 10:22:36 -0800 Subject: [PATCH 40/42] Implemented Brett's feedback --- committing.rst | 27 +++++---------------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/committing.rst b/committing.rst index 775d8c7572..1f89e4bfae 100644 --- a/committing.rst +++ b/committing.rst @@ -18,9 +18,10 @@ to enter the public source tree. Ask yourself the following questions: Read the linked b.p.o. issue. If there are ongoing discussions, then we need to have a resolution there before we can merge the pull request. -* **Was the pull request first made against the** ``master`` **branch?** +* **Was the pull request first made against the appropriate branch?** The only branch that receives new features is ``master``, the - in-development branch. + in-development branch. Pull requests should only target bug-fix branches + if an issue appears in only that version and possibly older versions. * **Are there comments on the pull request?** Look for explanations about whether the code coverage increased or @@ -32,18 +33,12 @@ to enter the public source tree. Ask yourself the following questions: the `issue tracker `_, or create a public fork of the repository. -* **Does the check on the pull request show that the test suite passes?** - :ref:`Run the entire test suite ` to ensure that it passes. - Running a single test is not enough since the changes may have unforeseen - effects on other tests or library modules. +* **Do the checks on the pull request show that the test suite passes?** + Make sure that all of the status checks are passing. * **Is the patch in a good state?** Check :ref:`patch` and :ref:`helptriage` to review what is expected of a patch. - -* **Do the changes meet the requirements of the patch checklist?** - :ref:`Run patchcheck ` to perform a confidence check and - flag extra whitespace. * **Does the patch break backwards-compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything @@ -51,9 +46,6 @@ to enter the public source tree. Ask yourself the following questions: be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. -* **Were** ``pyconfig.h.in`` **and** ``configure`` **regenerated?** - Regenerate them if necessary. - * **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core @@ -73,15 +65,6 @@ to enter the public source tree. Ask yourself the following questions: put in their GitHub username. For further questions about the CLA process, write to contributors@python.org. -* **Was the contributor added to** ``Misc/ACKS`` **?** - Make sure that the patch is attributed correctly with the contributor's - name in ``Misc/ACKS``. If the patch has been heavily modified, then - "Initial patch by " is an appropriate alternate wording. GitHub now - supports `multiple authors - `_ - in a commit. Add ``Co-authored-by: name `` at the end - of the commit message. - * **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (e.g. new features, significant improvements, or backwards-incompatible changes), then an From 91f046e6fe732301649e480167668795de728941 Mon Sep 17 00:00:00 2001 From: jablonskidev <36643503+jablonskidev@users.noreply.github.com> Date: Sat, 23 Jan 2021 10:28:39 -0800 Subject: [PATCH 41/42] Addressed issue #655 --- committing.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/committing.rst b/committing.rst index 1f89e4bfae..efd58ac149 100644 --- a/committing.rst +++ b/committing.rst @@ -45,6 +45,11 @@ to enter the public source tree. Ask yourself the following questions: still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. If you are unsure if the breakage is worth it, then ask on python-dev. + +* **Does documentation need to be updated?** + If the pull request introduces backwards-incompatible changes (e.g. + deprecating or removing a feature), then make sure that those changes + are reflected in the documentation before you merge the pull request. * **Were appropriate labels added to signify necessary backporting of the pull request?** If it is determined that a pull request needs to be From 6c46cfb6289ae8cdcaabe0851002c37cbb1da118 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 29 Jan 2021 16:16:54 -0800 Subject: [PATCH 42/42] Update committing.rst --- committing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/committing.rst b/committing.rst index efd58ac149..a242e8aa9b 100644 --- a/committing.rst +++ b/committing.rst @@ -165,7 +165,7 @@ Python repositories, so you need to be careful with your workflow: You can also push these branches to a separate public repository for maintenance work before it is integrated into the main repository. -* **You should not commit directly into the** ``master`` **branch, or any of the maintenance branches (currently 3.9 and 3.8).** +* **You should not commit directly into the** ``master`` **branch, or any of the maintenance branches.** You should commit against your own feature branch, and then create a pull request.