Skip to content

Commit cdc0df0

Browse files
sirosensirosen
committed
Reflow the quick reference into sections
Rather than trying to flatten the quick reference into a list (which is too compact!), reflow the doc with each list entry as a section or subsection. The steps are kept very similar to their prior content, but each now ends with a link to more detailed documentation, presented in a slightly more formulaic manner. Links out to GitHub are called out especially to ensure it's clear that they are not parts of the devguide.
1 parent fec3bf3 commit cdc0df0

1 file changed

Lines changed: 125 additions & 49 deletions

File tree

‎getting-started/quick-reference.rst‎

Lines changed: 125 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,91 +7,167 @@ Quick reference
77
Here are the basic steps needed to get set up and open a pull request.
88

99
This is meant as a checklist and cheat-sheet, not a comprehensive guide.
10-
For complete instructions please see the :ref:`setup guide <setup>`.
10+
For complete instructions please see the :ref:`setup guide <setup>` and the
11+
:ref:`pull request guide <pullrequest>`.
1112

12-
1. Install and set up :ref:`Git <vcsetup>` and other dependencies
13-
(see the :ref:`Git Setup <setup>` page for detailed information).
1413

15-
2. Fork `the CPython repository <https://github.com/python/cpython>`__
16-
to your GitHub account and :ref:`get the source code <checkout>` using::
14+
Setup Git
15+
=========
1716

18-
git clone https://github.com/<your_username>/cpython
19-
cd cpython
17+
Install and set up ``Git``.
2018

21-
3. Build Python:
19+
For detailed setup information, see :ref:`"Install Git" <vcsetup>`.
20+
There is also a more detailed :ref:`Git guide and cheat sheet <gitbootcamp>`.
2221

23-
.. tab:: Unix
22+
Fork and clone the repo
23+
-----------------------
2424

25-
.. code-block:: shell
25+
Fork `the CPython repository <https://github.com/python/cpython>`__
26+
to your GitHub account and :ref:`get the source code <checkout>` using::
2627

27-
./configure --config-cache --with-pydebug && make -j $(nproc)
28+
git clone https://github.com/<your_username>/cpython
29+
cd cpython
2830

29-
.. tab:: macOS
31+
We recommend also setting up ``pre-commit``::
3032

31-
.. code-block:: shell
33+
pre-commit install
3234

33-
./configure --config-cache --with-pydebug && make -j8
35+
For detailed information, see :ref:`"Get the source code" <checkout>` and
36+
:ref:`"Install pre-commit as a Git hook" <install-pre-commit>`.
3437

35-
.. tab:: Windows
3638

37-
.. code-block:: dosbatch
39+
Build Python
40+
============
3841

39-
PCbuild\build.bat -e -d
42+
.. tab:: Unix
4043

41-
See also :ref:`more detailed instructions <compiling>`,
42-
:ref:`how to install and build dependencies <build-dependencies>`,
43-
and the platform-specific pages for :ref:`Unix <unix-compiling>`,
44-
:ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
44+
.. code-block:: shell
4545
46-
4. :ref:`Run the tests <runtests>`:
46+
./configure --config-cache --with-pydebug && make -j $(nproc)
4747
48-
.. tab:: Unix
48+
.. tab:: macOS
4949

50-
.. code-block:: shell
50+
.. code-block:: shell
5151
52-
./python -m test -j3
52+
./configure --config-cache --with-pydebug && make -j8
5353
54-
.. tab:: macOS
54+
.. tab:: Windows
5555

56-
.. code-block:: shell
56+
.. code-block:: dosbatch
5757
58-
./python.exe -m test -j8
58+
PCbuild\build.bat -e -d
5959
60-
.. note::
61-
:ref:`Most <mac-python.exe>` macOS systems use
62-
:file:`./python.exe` in order to avoid filename conflicts with
63-
the ``Python`` directory.
60+
See also :ref:`more detailed instructions <compiling>`,
61+
:ref:`how to install and build dependencies <build-dependencies>`,
62+
and the platform-specific pages for :ref:`Unix <unix-compiling>`,
63+
:ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
6464

65-
.. tab:: Windows
6665

67-
.. code-block:: dosbatch
66+
Run the tests
67+
=============
6868

69-
.\python.bat -m test -j3
69+
.. tab:: Unix
7070

71-
5. Create a new branch where your work for the issue will go, for example::
71+
.. code-block:: shell
7272
73-
git checkout -b fix-issue-12345 main
73+
./python -m test -j3
7474
75-
If an issue does not already exist, please `create it
76-
<https://github.com/python/cpython/issues>`__. Trivial issues (for example, typos) do
77-
not require an issue.
75+
.. tab:: macOS
7876

79-
6. Push the branch on your fork on GitHub and :ref:`create a pull request
80-
<pullrequest>`. Include the issue number using ``gh-NNNNNN`` in the
81-
pull request title. For example:
77+
.. code-block:: shell
8278
83-
.. code-block:: text
79+
./python.exe -m test -j8
8480
85-
gh-12345: Fix some bug in spam module
81+
.. note::
82+
:ref:`Most <mac-python.exe>` macOS systems use
83+
:file:`./python.exe` in order to avoid filename conflicts with
84+
the ``Python`` directory.
8685

87-
7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The
88-
news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`__,
89-
or the :pypi:`blurb` tool and its ``blurb add``
90-
command. Please read more about ``blurb`` in its
86+
.. tab:: Windows
87+
88+
.. code-block:: dosbatch
89+
90+
.\python.bat -m test -j3
91+
92+
93+
See also :ref:`how to write and run tests <run-write-tests>`.
94+
95+
96+
Create issues and pull requests
97+
===============================
98+
99+
Create issues for nontrivial changes
100+
------------------------------------
101+
102+
For most changes, `create an issue <https://github.com/python/cpython/issues>`__
103+
before submitting a pull request.
104+
Trivial changes like typo fixes do not need issues.
105+
106+
Create work branches
107+
--------------------
108+
109+
Work on a feature or fix in a new branch in Git from the ``main`` branch::
110+
111+
git checkout -b fix-issue-12345 main
112+
113+
Make changes, then :ref:`commit <commit-changes>` and
114+
:ref:`push to your fork <push-changes>`.
115+
116+
Document your changes
117+
---------------------
118+
119+
Many changes deserve a NEWS entry which documents what changed.
120+
121+
Add a News entry into the ``Misc/NEWS.d/`` directory as individual file.
122+
The news entry can be created by using
123+
`blurb-it <https://blurb-it.herokuapp.com/>`__,
124+
or the :pypi:`blurb` tool and its ``blurb add`` command.
125+
126+
.. tip::
127+
128+
You can read more about ``blurb`` in its
91129
`repository <https://github.com/python/blurb>`__.
92130

131+
For more information on writing news entries,
132+
see :ref:`"Updating NEWS and What's New in Python" <news-entry>`.
133+
134+
Create pull requests
135+
--------------------
136+
137+
Create pull bequests on GitHub from your branches, on your fork, and make sure
138+
to put the relevant issue number in ``gh-NNNNNN``` format in the pull request title.
139+
For example:
140+
141+
.. code-block:: text
142+
143+
gh-12345: Fix some bug in spam module
144+
145+
See also, GitHub's documentation on `creating Pull Requests`_.
146+
147+
For more detailed guidance, follow the :ref:`step-by-step pull request guide <pullrequest-steps>`.
148+
93149
.. note::
94150

95151
First time contributors will need to sign the Contributor Licensing
96152
Agreement (CLA) as described in the :ref:`Licensing <cla>` section of
97153
this guide.
154+
155+
.. _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
156+
157+
Work on your pull request
158+
-------------------------
159+
160+
Make sure the
161+
:ref:`continuous integration checks on your Pull Request are green <keeping-ci-green>` (successful).
162+
163+
Read and respond to reviewer comments on your pull request.
164+
165+
See also, GitHub's documentation on `commenting on Pull Requests`_.
166+
167+
.. note::
168+
169+
Don't force-push. Reviewers often want to look at individual commits.
170+
171+
CPython uses squash merges, so PRs will end up as single commits when merged.
172+
173+
.. _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

0 commit comments

Comments
 (0)