Skip to content

Commit 0164145

Browse files
sirosenhugovkStanFromIrelandwillingc
authored
Move the "quick reference" to a dedicated page (#1838)
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Carol Willing <2680980+willingc@users.noreply.github.com>
1 parent bad7be5 commit 0164145

4 files changed

Lines changed: 193 additions & 142 deletions

File tree

‎getting-started/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Getting started
77
.. toctree::
88
:maxdepth: 5
99

10+
quick-reference
1011
setup-building
1112
fixing-issues
1213
git-boot-camp

‎getting-started/pull-request-lifecycle.rst‎

Lines changed: 18 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -16,58 +16,8 @@ that you create a branch in Git, make your changes, push those changes
1616
to your fork on GitHub (``origin``), and then create a pull request against
1717
the official CPython repository (``upstream``).
1818

19-
20-
.. _pullrequest-quickguide:
21-
22-
Quick guide
23-
===========
24-
25-
`Clear communication`_ is key to contributing to any project, especially an
26-
`Open Source`_ project like CPython.
27-
28-
Here is a quick overview of how you can contribute to CPython:
29-
30-
#. `Create an issue`_ that describes your change. If it is trivial
31-
(like :ref:`typo fixes <typo-fixes>`), or an issue already exists,
32-
you can skip this step.
33-
34-
#. :ref:`Create a new branch in Git <pullrequest-steps>` from the
35-
``main`` branch
36-
37-
#. Work on changes: fix a bug or add a new feature
38-
39-
#. :ref:`Run tests <runtests>` and ``make patchcheck``
40-
41-
#. :ref:`Commit <commit-changes>` and :ref:`push <push-changes>`
42-
changes to your GitHub fork
43-
44-
#. `Create Pull Request`_ on GitHub to merge a branch from your fork
45-
46-
#. Make sure the :ref:`continuous integration checks on your Pull Request
47-
are green <keeping-ci-green>` (successful)
48-
49-
#. Review and address `comments on your Pull Request`_
50-
51-
#. When your changes are merged, you can :ref:`delete the PR branch
52-
<deleting_branches>`
53-
54-
#. Celebrate contributing to CPython! :)
55-
56-
Don't force-push
57-
----------------
58-
59-
In order to keep the commit history intact, please avoid squashing or amending
60-
history and then force-pushing to the PR. Reviewers often want to look at
61-
individual commits.
62-
When the PR is merged, everything will be squashed into a single commit.
63-
64-
.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution
65-
.. _Open Source: https://opensource.guide/
66-
.. _create an issue: https://github.com/python/cpython/issues
67-
.. _CPython: https://github.com/python/cpython
68-
.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/
69-
.. _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
70-
.. _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
19+
For a cheat-sheet reference, see the
20+
:ref:`quick reference on creating pull requests <pullrequest-quickguide>`.
7121

7222

7323
.. _pullrequest-steps:
@@ -185,6 +135,15 @@ message. It is usually okay to leave that as-is and close the editor.
185135
See `the merge command's documentation <https://git-scm.com/docs/git-merge>`__
186136
for a detailed technical explanation.
187137

138+
Don't force-push
139+
----------------
140+
141+
In order to keep the commit history intact, avoid squashing or amending
142+
history and then force-pushing to the PR.
143+
Reviewers often want to look at individual commits.
144+
145+
CPython uses squash merges, so PRs will end up as single commits when merged.
146+
188147

189148
.. _good-prs:
190149

@@ -290,13 +249,20 @@ in the "What's New in Python" entry.
290249
A change that needs an entry in "What's New in Python"
291250
is very likely not suitable for inclusion in a maintenance release.
292251

252+
.. _news-entry-howto:
253+
293254
How to add a NEWS entry
294255
-----------------------
295256

296257
``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The
297258
``NEWS`` entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`_,
298259
or the :pypi:`blurb` tool and its ``blurb add`` command.
299260

261+
.. tip::
262+
263+
You can read more about ``blurb`` in its
264+
:github:`repository <python/blurb>`.
265+
300266
If you are unable to use the tool, then you can create the ``NEWS`` entry file
301267
manually. The ``Misc/NEWS.d`` directory contains a sub-directory named
302268
``next``, which contains various sub-directories representing classifications

‎getting-started/quick-reference.rst‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
.. _quick-reference:
2+
3+
===============
4+
Quick reference
5+
===============
6+
7+
.. include:: /include/activate-tab.rst
8+
9+
Here are the basic steps needed to get set up and open a pull request.
10+
11+
This is meant as a checklist and cheat-sheet, not a comprehensive guide.
12+
For complete instructions see the :ref:`setup guide <setup>` and the
13+
:ref:`pull request guide <pullrequest>`.
14+
15+
16+
Set up Git
17+
==========
18+
19+
Install and set up ``Git``.
20+
21+
For detailed setup information, see :ref:`"Install Git" <vcsetup>`.
22+
There is also a more detailed :ref:`Git guide and cheat sheet <gitbootcamp>`.
23+
24+
Fork and clone the repo
25+
-----------------------
26+
27+
Fork `the CPython repository <https://github.com/python/cpython>`__
28+
to your GitHub account and clone the repo using::
29+
30+
git clone https://github.com/<your_username>/cpython
31+
cd cpython
32+
33+
For detailed information, see :ref:`"Get the source code" <checkout>`.
34+
35+
36+
Build Python
37+
============
38+
39+
.. tab:: Unix
40+
41+
.. code-block:: shell
42+
43+
./configure --config-cache --with-pydebug && make -j $(nproc)
44+
45+
.. tab:: macOS
46+
47+
.. code-block:: shell
48+
49+
./configure --config-cache --with-pydebug && make -j$(sysctl -n hw.logicalcpu)
50+
51+
.. tab:: Windows
52+
53+
.. code-block:: dosbatch
54+
55+
PCbuild\build.bat -e -d
56+
57+
See also :ref:`more detailed instructions <compiling>`,
58+
:ref:`how to install and build dependencies <build-dependencies>`,
59+
and the platform-specific pages for :ref:`Unix <unix-compiling>`,
60+
:ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
61+
62+
63+
Run the tests
64+
=============
65+
66+
.. tab:: Unix
67+
68+
.. code-block:: shell
69+
70+
./python -m test -j0
71+
72+
.. tab:: macOS
73+
74+
.. code-block:: shell
75+
76+
./python.exe -m test -j0
77+
78+
.. note::
79+
:ref:`Most <mac-python.exe>` macOS systems use
80+
:file:`./python.exe` in order to avoid filename conflicts with
81+
the ``Python`` directory.
82+
83+
.. tab:: Windows
84+
85+
.. code-block:: dosbatch
86+
87+
.\python.bat -m test -j0
88+
89+
90+
See also :ref:`how to write and run tests <run-write-tests>`.
91+
92+
93+
.. _pullrequest-quickguide:
94+
95+
Create issues and pull requests
96+
===============================
97+
98+
Create issues for nontrivial changes
99+
------------------------------------
100+
101+
For most changes, `create an issue <https://github.com/python/cpython/issues>`__
102+
before submitting a pull request.
103+
Trivial changes like typo fixes do not need issues.
104+
105+
Create work branches
106+
--------------------
107+
108+
Work on a feature or fix in a new branch in Git from the ``main`` branch::
109+
110+
git checkout -b fix-issue-12345 main
111+
112+
Make changes, then :ref:`commit <commit-changes>` and
113+
:ref:`push to your fork <push-changes>`.
114+
115+
Document your changes
116+
---------------------
117+
118+
Many changes deserve a NEWS entry which documents what changed.
119+
For more information on how and when to write news entries,
120+
see :ref:`"Updating NEWS and What's New in Python" <news-entry>`.
121+
122+
A news entry can be created locally with the :pypi:`blurb` tool
123+
and its ``blurb add`` command or online after a pull request has
124+
been opened with `blurb-it <https://blurb-it.herokuapp.com/>`__.
125+
126+
For more information about how to create news entries, see
127+
:ref:`"How to add a NEWS entry" <news-entry-howto>`.
128+
129+
Create pull requests
130+
--------------------
131+
132+
Create pull requests on GitHub from your branches, on your fork, and make sure
133+
to put the relevant issue number in ``gh-NNNNNN`` format in the pull request title.
134+
For example:
135+
136+
.. code-block:: text
137+
138+
gh-12345: Fix some bug in spam module
139+
140+
See also, GitHub's documentation on `creating pull requests`_.
141+
142+
For more detailed guidance, follow the :ref:`step-by-step pull request guide <pullrequest-steps>`.
143+
144+
.. note::
145+
146+
First time contributors will need to sign the Contributor Licensing
147+
Agreement (CLA) as described in the :ref:`Licensing <cla>` section of
148+
this guide.
149+
150+
.. _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
151+
152+
Work on your pull request
153+
-------------------------
154+
155+
Make sure the :ref:`continuous integration checks on your pull
156+
request are green <keeping-ci-green>` (successful).
157+
158+
Read and respond to reviewer comments on your pull request.
159+
160+
See also, GitHub's documentation on `commenting on pull requests`_.
161+
162+
.. _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
163+
164+
Don't force-push
165+
----------------
166+
167+
In order to keep the commit history intact, avoid squashing or amending
168+
history and then force-pushing to the PR.
169+
Reviewers often want to look at individual commits.
170+
171+
CPython uses squash merges, so PRs will end up as single commits when merged.

‎index.rst‎

Lines changed: 3 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -74,102 +74,15 @@ For example,
7474
:width: 100%
7575

7676

77-
.. _quick-reference:
78-
7977
Quick reference
8078
---------------
8179

82-
Here are the basic steps needed to get set up and open a pull request.
83-
This is meant as a checklist, once you know the basics. For complete
84-
instructions please see the :ref:`setup guide <setup>`.
85-
86-
1. Install and set up :ref:`Git <vcsetup>` and other dependencies
87-
(see the :ref:`Git Setup <setup>` page for detailed information).
88-
89-
2. Fork `the CPython repository <https://github.com/python/cpython>`__
90-
to your GitHub account and :ref:`get the source code <checkout>` using::
91-
92-
git clone https://github.com/<your_username>/cpython
93-
cd cpython
94-
95-
3. Build Python:
96-
97-
.. tab:: Unix
98-
99-
.. code-block:: shell
100-
101-
./configure --config-cache --with-pydebug && make -j $(nproc)
102-
103-
.. tab:: macOS
104-
105-
.. code-block:: shell
106-
107-
./configure --config-cache --with-pydebug && make -j8
108-
109-
.. tab:: Windows
110-
111-
.. code-block:: dosbatch
112-
113-
PCbuild\build.bat -e -d
114-
115-
See also :ref:`more detailed instructions <compiling>`,
116-
:ref:`how to install and build dependencies <build-dependencies>`,
117-
and the platform-specific pages for :ref:`Unix <unix-compiling>`,
118-
:ref:`macOS <macOS>`, and :ref:`Windows <windows-compiling>`.
119-
120-
4. :ref:`Run the tests <runtests>`:
121-
122-
.. tab:: Unix
123-
124-
.. code-block:: shell
125-
126-
./python -m test -j3
127-
128-
.. tab:: macOS
129-
130-
.. code-block:: shell
131-
132-
./python.exe -m test -j8
133-
134-
.. note::
135-
:ref:`Most <mac-python.exe>` macOS systems use
136-
:file:`./python.exe` in order to avoid filename conflicts with
137-
the ``Python`` directory.
138-
139-
.. tab:: Windows
140-
141-
.. code-block:: dosbatch
142-
143-
.\python.bat -m test -j3
144-
145-
5. Create a new branch where your work for the issue will go, for example::
146-
147-
git checkout -b fix-issue-12345 main
148-
149-
If an issue does not already exist, please `create it
150-
<https://github.com/python/cpython/issues>`__. Trivial issues (for example, typos) do
151-
not require an issue.
152-
153-
6. Push the branch on your fork on GitHub and :ref:`create a pull request
154-
<pullrequest>`. Include the issue number using ``gh-NNNNNN`` in the
155-
pull request title. For example:
156-
157-
.. code-block:: text
158-
159-
gh-12345: Fix some bug in spam module
160-
161-
7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The
162-
news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`__,
163-
or the :pypi:`blurb` tool and its ``blurb add``
164-
command. Please read more about ``blurb`` in its
165-
`repository <https://github.com/python/blurb>`__.
166-
16780
.. note::
16881

169-
First time contributors will need to sign the Contributor Licensing
170-
Agreement (CLA) as described in the :ref:`Licensing <cla>` section of
171-
this guide.
82+
The quick reference documentation has been moved to serve as a cheat-sheet and overview
83+
in :ref:`Getting started <getting-started>`.
17284

85+
Go to :ref:`the new quick reference <quick-reference>`.
17386

17487
Proposing changes to Python itself
17588
----------------------------------

0 commit comments

Comments
 (0)