From 9a62b60d0654be53aaf7a37022ec6b8a29f2f0da Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 13 Jun 2026 18:39:41 -0500 Subject: [PATCH] Move the "quick reference" to a dedicated page A new page at `Getting Started > Quick Reference` is added to contain the (moved) content which was in the Quick Reference section of the index document for the site. The content is left almost entirely untouched, but the introductory text is slightly altered to de-emphasize use of the doc for new contributors. Intentionally, as described in #1837, the page is placed in Getting Started but after the setup guide. --- getting-started/index.rst | 1 + getting-started/quick-reference.rst | 97 +++++++++++++++++++++++++++++ index.rst | 97 ----------------------------- 3 files changed, 98 insertions(+), 97 deletions(-) create mode 100644 getting-started/quick-reference.rst diff --git a/getting-started/index.rst b/getting-started/index.rst index 48037ad38..8b0338ccf 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -8,6 +8,7 @@ Getting started :maxdepth: 5 setup-building + quick-reference fixing-issues git-boot-camp pull-request-lifecycle diff --git a/getting-started/quick-reference.rst b/getting-started/quick-reference.rst new file mode 100644 index 000000000..d3a53a371 --- /dev/null +++ b/getting-started/quick-reference.rst @@ -0,0 +1,97 @@ +.. _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 and cheat-sheet, not a comprehensive guide. +For complete instructions please see the :ref:`setup guide `. + +1. Install and set up :ref:`Git ` and other dependencies + (see the :ref:`Git Setup ` page for detailed information). + +2. Fork `the CPython repository `__ + to your GitHub account and :ref:`get the source code ` using:: + + git clone https://github.com//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 `, + :ref:`how to install and build dependencies `, + and the platform-specific pages for :ref:`Unix `, + :ref:`macOS `, and :ref:`Windows `. + +4. :ref:`Run the tests `: + + .. tab:: Unix + + .. code-block:: shell + + ./python -m test -j3 + + .. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test -j8 + + .. note:: + :ref:`Most ` 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 + `__. 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 + `. 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 `__, + or the :pypi:`blurb` tool and its ``blurb add`` + command. Please read more about ``blurb`` in its + `repository `__. + +.. note:: + + First time contributors will need to sign the Contributor Licensing + Agreement (CLA) as described in the :ref:`Licensing ` section of + this guide. diff --git a/index.rst b/index.rst index f6bd875f0..6038c32f5 100644 --- a/index.rst +++ b/index.rst @@ -74,103 +74,6 @@ 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 `. - -1. Install and set up :ref:`Git ` and other dependencies - (see the :ref:`Git Setup ` page for detailed information). - -2. Fork `the CPython repository `__ - to your GitHub account and :ref:`get the source code ` using:: - - git clone https://github.com//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 `, - :ref:`how to install and build dependencies `, - and the platform-specific pages for :ref:`Unix `, - :ref:`macOS `, and :ref:`Windows `. - -4. :ref:`Run the tests `: - - .. tab:: Unix - - .. code-block:: shell - - ./python -m test -j3 - - .. tab:: macOS - - .. code-block:: shell - - ./python.exe -m test -j8 - - .. note:: - :ref:`Most ` 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 - `__. 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 - `. 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 `__, - or the :pypi:`blurb` tool and its ``blurb add`` - command. Please read more about ``blurb`` in its - `repository `__. - -.. note:: - - First time contributors will need to sign the Contributor Licensing - Agreement (CLA) as described in the :ref:`Licensing ` section of - this guide. - - Proposing changes to Python itself ----------------------------------