Move the "quick reference" to a dedicated page

getting-started/index.rst

@@ -7,6 +7,7 @@ Getting started
 .. toctree::
    :maxdepth: 5
 
+   quick-reference
    setup-building
    fixing-issues
    git-boot-camp

getting-started/pull-request-lifecycle.rst

@@ -16,58 +16,8 @@ that you create a branch in Git, make your changes, push those changes
 to your fork on GitHub (``origin``), and then create a pull request against
 the official CPython repository (``upstream``).
 
-
-.. _pullrequest-quickguide:
-
-Quick guide
-===========
-
-`Clear communication`_ is key to contributing to any project, especially an
-`Open Source`_ project like CPython.
-
-Here is a quick overview of how you can contribute to CPython:
-
-#. `Create an issue`_ that describes your change. If it is trivial
-   (like :ref:`typo fixes <typo-fixes>`), or an issue already exists,
-   you can skip this step.
-
-#. :ref:`Create a new branch in Git <pullrequest-steps>` from the
-   ``main`` branch
-
-#. Work on changes: fix a bug or add a new feature
-
-#. :ref:`Run tests <runtests>` and ``make patchcheck``
-
-#. :ref:`Commit <commit-changes>` and :ref:`push <push-changes>`
-   changes to your GitHub fork
-
-#. `Create Pull Request`_ on GitHub to merge a branch from your fork
-
-#. Make sure the :ref:`continuous integration checks on your Pull Request
-   are green <keeping-ci-green>` (successful)
-
-#. Review and address `comments on your Pull Request`_
-
-#. When your changes are merged, you can :ref:`delete the PR branch
-   <deleting_branches>`
-
-#. Celebrate contributing to CPython! :)
-
-Don't force-push
-----------------
-
-In order to keep the commit history intact, please avoid squashing or amending
-history and then force-pushing to the PR. Reviewers often want to look at
-individual commits.
-When the PR is merged, everything will be squashed into a single commit.
-
-.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution
-.. _Open Source: https://opensource.guide/
-.. _create an issue: https://github.com/python/cpython/issues
-.. _CPython: https://github.com/python/cpython
-.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/
-.. _Create Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
-.. _comments on your Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request
+For a cheat-sheet reference, see the
+:ref:`quick reference on creating pull requests <pullrequest-quickguide>`.
 
 
 .. _pullrequest-steps:
@@ -185,6 +135,15 @@ message. It is usually okay to leave that as-is and close the editor.
 See `the merge command's documentation <https://git-scm.com/docs/git-merge>`__
 for a detailed technical explanation.
 
+Don't force-push
+----------------
+
+In order to keep the commit history intact, avoid squashing or amending
+history and then force-pushing to the PR.
+Reviewers often want to look at individual commits.
+
+CPython uses squash merges, so PRs will end up as single commits when merged.
+
 
 .. _good-prs:
 
@@ -290,13 +249,20 @@ in the "What's New in Python" entry.
     A change that needs an entry in "What's New in Python"
     is very likely not suitable for inclusion in a maintenance release.
 
+.. _news-entry-howto:
+
 How to add a NEWS entry
 -----------------------
 
 ``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The
 ``NEWS`` entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`_,
 or the :pypi:`blurb` tool and its ``blurb add`` command.
 
+.. tip::
+
+   You can read more about ``blurb`` in its
+   :github:`repository <python/blurb>`.
+
 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

getting-started/quick-reference.rst

@@ -0,0 +1,171 @@
+.. _quick-reference:
+
+===============
+Quick reference
+===============
+
+.. include:: /include/activate-tab.rst
+
+Here are the basic steps needed to get set up and open a pull request.
+
+This is meant as a checklist and cheat-sheet, not a comprehensive guide.
+For complete instructions see the :ref:`setup guide <setup>` and the
+:ref:`pull request guide <pullrequest>`.
+
+
+Set up Git
+==========
+
+Install and set up ``Git``.
+
+For detailed setup information, see :ref:`"Install Git" <vcsetup>`.
+There is also a more detailed :ref:`Git guide and cheat sheet <gitbootcamp>`.
+
+Fork and clone the repo
+-----------------------
+
+Fork `the CPython repository <https://github.com/python/cpython>`__
+to your GitHub account and clone the repo using::
+
+   git clone https://github.com/<your_username>/cpython
+   cd cpython
+
+For detailed information, see :ref:`"Get the source code" <checkout>`.
+
+
+Build Python
+============
+
+.. tab:: Unix
+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j $(nproc)
+
+.. tab:: macOS
+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j$(sysctl -n hw.logicalcpu)
+
+.. tab:: Windows
+
+   .. code-block:: dosbatch
+
+      PCbuild\build.bat -e -d
+
+See also :ref:`more detailed instructions <compiling>`,
+:ref:`how to install and build dependencies <build-dependencies>`,
+and the platform-specific pages for :ref:`Unix <unix-compiling>`,
+:ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
+
+
+Run the tests
+=============
+
+.. tab:: Unix
+
+   .. code-block:: shell
+
+      ./python -m test -j0
+
+.. tab:: macOS
+
+   .. code-block:: shell
+
+      ./python.exe -m test -j0
+
+   .. note::
+      :ref:`Most <mac-python.exe>` macOS systems use
+      :file:`./python.exe` in order to avoid filename conflicts with
+      the ``Python`` directory.
+
+.. tab:: Windows
+
+   .. code-block:: dosbatch
+
+      .\python.bat -m test -j0
+
+
+See also :ref:`how to write and run tests <run-write-tests>`.
+
+
+.. _pullrequest-quickguide:
+
+Create issues and pull requests
+===============================
+
+Create issues for nontrivial changes
+------------------------------------
+
+For most changes, `create an issue <https://github.com/python/cpython/issues>`__
+before submitting a pull request.
+Trivial changes like typo fixes do not need issues.
+
+Create work branches
+--------------------
+
+Work on a feature or fix in a new branch in Git from the ``main`` branch::
+
+   git checkout -b fix-issue-12345 main
+
+Make changes, then :ref:`commit <commit-changes>` and
+:ref:`push to your fork <push-changes>`.
+
+Document your changes
+---------------------
+
+Many changes deserve a NEWS entry which documents what changed.
+For more information on how and when to write news entries,
+see :ref:`"Updating NEWS and What's New in Python" <news-entry>`.
+
+A news entry can be created locally with the :pypi:`blurb` tool
+and its ``blurb add`` command or online after a pull request has
+been opened with `blurb-it <https://blurb-it.herokuapp.com/>`__.
+
+For more information about how to create news entries, see
+:ref:`"How to add a NEWS entry" <news-entry-howto>`.
+
+Create pull requests
+--------------------
+
+Create pull requests on GitHub from your branches, on your fork, and make sure
+to put the relevant issue number in ``gh-NNNNNN`` format in the pull request title.
+For example:
+
+.. code-block:: text
+
+   gh-12345: Fix some bug in spam module
+
+See also, GitHub's documentation on `creating pull requests`_.
+
+For more detailed guidance, follow the :ref:`step-by-step pull request guide <pullrequest-steps>`.
+
+.. note::
+
+   First time contributors will need to sign the Contributor Licensing
+   Agreement (CLA) as described in the :ref:`Licensing <cla>` section of
+   this guide.
+
+.. _creating pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+Work on your pull request
+-------------------------
+
+Make sure the :ref:`continuous integration checks on your pull
+request are green <keeping-ci-green>` (successful).
+
+Read and respond to reviewer comments on your pull request.
+
+See also, GitHub's documentation on `commenting on pull requests`_.
+
+.. _commenting on pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request
+
+Don't force-push
+----------------
+
+In order to keep the commit history intact, avoid squashing or amending
+history and then force-pushing to the PR.
+Reviewers often want to look at individual commits.
+
+CPython uses squash merges, so PRs will end up as single commits when merged.

index.rst

@@ -74,102 +74,15 @@ For example,
          :width: 100%
 
 
-.. _quick-reference:
-
 Quick reference
 ---------------
 
-Here are the basic steps needed to get set up and open a pull request.
-This is meant as a checklist, once you know the basics. For complete
-instructions please see the :ref:`setup guide <setup>`.
-
-1. Install and set up :ref:`Git <vcsetup>` and other dependencies
-   (see the :ref:`Git Setup <setup>` page for detailed information).
-
-2. Fork `the CPython repository <https://github.com/python/cpython>`__
-   to your GitHub account and :ref:`get the source code <checkout>` using::
-
-      git clone https://github.com/<your_username>/cpython
-      cd cpython
-
-3. Build Python:
-
-   .. tab:: Unix
-
-      .. code-block:: shell
-
-         ./configure --config-cache --with-pydebug && make -j $(nproc)
-
-   .. tab:: macOS
-
-      .. code-block:: shell
-
-         ./configure --config-cache --with-pydebug && make -j8
-
-   .. tab:: Windows
-
-      .. code-block:: dosbatch
-
-         PCbuild\build.bat -e -d
-
-   See also :ref:`more detailed instructions <compiling>`,
-   :ref:`how to install and build dependencies <build-dependencies>`,
-   and the platform-specific pages for :ref:`Unix <unix-compiling>`,
-   :ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
-
-4. :ref:`Run the tests <runtests>`:
-
-   .. tab:: Unix
-
-      .. code-block:: shell
-
-         ./python -m test -j3
-
-   .. tab:: macOS
-
-      .. code-block:: shell
-
-         ./python.exe -m test -j8
-
-      .. note::
-         :ref:`Most <mac-python.exe>` macOS systems use
-         :file:`./python.exe` in order to avoid filename conflicts with
-         the ``Python`` directory.
-
-   .. tab:: Windows
-
-      .. code-block:: dosbatch
-
-         .\python.bat -m test -j3
-
-5. Create a new branch where your work for the issue will go, for example::
-
-      git checkout -b fix-issue-12345 main
-
-   If an issue does not already exist, please `create it
-   <https://github.com/python/cpython/issues>`__.  Trivial issues (for example, typos) do
-   not require an issue.
-
-6. Push the branch on your fork on GitHub and :ref:`create a pull request
-   <pullrequest>`.  Include the issue number using ``gh-NNNNNN`` in the
-   pull request title.  For example:
-
-   .. code-block:: text
-
-      gh-12345: Fix some bug in spam module
-
-7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The
-   news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`__,
-   or the :pypi:`blurb` tool and its ``blurb add``
-   command. Please read more about ``blurb`` in its
-   `repository <https://github.com/python/blurb>`__.
-
 .. note::
 
-   First time contributors will need to sign the Contributor Licensing
-   Agreement (CLA) as described in the :ref:`Licensing <cla>` section of
-   this guide.
+   The quick reference documentation has been moved to serve as a cheat-sheet and overview
+   in :ref:`Getting started <getting-started>`.
 
+Go to :ref:`the new quick reference <quick-reference>`.
 
 Proposing changes to Python itself
 ----------------------------------