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 ----------------------------------