Skip to content

Move the "quick reference" to a dedicated page #1838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
willingc merged 15 commits into from
Jun 25, 2026
+193 −142
Merged

Move the "quick reference" to a dedicated page #1838

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
9a62b60
Move the "quick reference" to a dedicated page
sirosen Jun 13, 2026
543e002
Change "Quick reference" to sentence-case
sirosen Jun 17, 2026
fec3bf3
Move the quick reference section to be first
sirosen Jun 20, 2026
cdc0df0
Reflow the quick reference into sections
sirosen Jun 21, 2026
5e7e09e
Replace the PR quickguide with a link
sirosen Jun 21, 2026
86f942c
Restore a "continuity" quick-reference section
sirosen Jun 21, 2026
1a76f5e
Apply suggestions from code review
sirosen Jun 22, 2026
09e61f7
Apply suggestions from code review
sirosen Jun 24, 2026
a908456
Remove pre-commit instructions from quick reference
sirosen Jun 24, 2026
1931332
Refine quick-reference explanation of NEWS entries
sirosen Jun 24, 2026
608a224
Apply suggestions from code review
sirosen Jun 24, 2026
85825ba
Minor adjustment to move a link definition
sirosen Jun 24, 2026
7f14dbc
Update getting-started/quick-reference.rst
sirosen Jun 25, 2026
e54a2bb
Apply suggestions from code review
sirosen Jun 25, 2026
0265531
Reintroduce 'dont-force-push' on PR lifecycle
sirosen Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions getting-started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Getting started
.. toctree::
:maxdepth: 5

quick-reference
Comment thread
willingc marked this conversation as resolved.
setup-building
fixing-issues
git-boot-camp
Expand Down
54 changes: 2 additions & 52 deletions getting-started/pull-request-lifecycle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
willingc marked this conversation as resolved.
----------------

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:
Expand Down
177 changes: 177 additions & 0 deletions getting-started/quick-reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
.. _quick-reference:

===============
Quick reference
===============
Comment thread
sirosen marked this conversation as resolved.

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 <setup>` and the
Comment thread
sirosen marked this conversation as resolved.
Outdated
:ref:`pull request guide <pullrequest>`.


Setup Git
=========
Comment thread
sirosen marked this conversation as resolved.
Outdated

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 :ref:`get the source code <checkout>` using::

git clone https://github.com/<your_username>/cpython
cd cpython

We recommend also setting up ``pre-commit``::

@StanFromIreland StanFromIreland Jun 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@encukou, are you happy to do this now that we've hash-pinned all the third party hooks?

@encukou encukou Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the policy on updating those hash-pins?

(FWIW, you don't need to make me happy. Just Seth ;)

@hugovk hugovk Jun 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None yet.

I'd like to automate with either:

  • https://pre-commit.ci to auto-update them weekly, monthly or quarterly (my pick is quarterly). This can also autofix formatting in PRs, often a tedious thing to ask contributors to do (we can also configure to disable that, my preference is to leave enabled).

  • Dependabot: we're already using this for bumping GitHub Actions and pip dependencies. Interval can be daily, weekly, monthly, quarterly, semiannually, yearly, or a custom cron. It won't autofix PRs. We can also configure cooldowns.

And we can manually update when we need a new feature or bugfix.

@sirosen sirosen Jun 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I take it that there was some discussion about ensuring these are pinned for safety. 😁

I use pre-commit.ci for this in most of my projects, and the autofixing is quite nice.

If the autofixing isn't desirable, I'd tend towards Dependabot, since the infrastructure is provided by GitHub. (I think this is nicer in having fewer providers and putting less load on a smaller platform.)

@encukou encukou Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@encukou, are you happy to do this now

No, this doesn't spark joy here. It don't want to recommend this setup. But I won't block it, if it's not mandatory.

From pre-commit.ci problem statement:

Developers spend a fair chunk of time during their development flow on fixing relatively trivial problems in their code.

I see this differently. Developers spend a fair chunk of time looking at code while their fingers are engaged.
Auto-fixing style issues often gives code the superficial appearance of quality -- it looks like someone spent time polishing it, but without the deeper benefits.
If we want to avoid the tedium, let us simply tolerate the occasional lack of trailing comma or over-long line.

That said, I agree that there are automatic checks that are useful -- unused import, ReST single-backquotes, or security scans, but they seem to be in the minority -- and I don't think they're worth installing locally before you first build CPython.

@willingc willingc Jun 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have similar feelings as @encukou about autofix (though I do have it enabled on CI in other projects. In general, I would have CI run the pre-commit run. Locally, I think it should be optional, not recommended (a subtle difference).

Folks, I think this is the only item that needs a decision after cleanup of a few commands where there is consensus. Let's try to converge so that we can merge. Thanks!

@nedbat nedbat Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps I've missed something, but it seems that the original page didn't mention pre-commit, and this is an addition. Since the goal of this PR is to move content, and this point is becoming difficult, shouldn't we let the status quo win and not add pre-commit now?

@sirosen sirosen Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this was something I added, in the course of walking through the original and cross-checking it against the full guide.

I hadn't expected it to be contentious, as it's documented as "recommended" in the more complete docs. I would be okay with changing that to "optional" here.

That said, I prefer dropping it. Doing so makes the guide shorter, and this is meant to be a "quick reference". I'll plan to do that when I come back to apply (final? 🤞 ) changes, probably in a few hours time.

@willingc willingc Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's drop it. We can always add it in a future PR.


pre-commit install

For detailed information, see :ref:`"Get the source code" <checkout>` and
:ref:`"Install pre-commit as a Git hook" <install-pre-commit>`.


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
Comment thread
sirosen marked this conversation as resolved.
Outdated

.. 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 -j3
Comment thread
sirosen marked this conversation as resolved.
Outdated

.. tab:: macOS

.. code-block:: shell

./python.exe -m test -j8
Comment thread
sirosen marked this conversation as resolved.
Outdated

.. note::
:ref:`Most <mac-python.exe>` macOS systems use
:file:`./python.exe` in order to avoid filename conflicts with
the ``Python`` directory.
Comment thread
StanFromIreland marked this conversation as resolved.

.. tab:: Windows

.. code-block:: dosbatch

.\python.bat -m test -j3
Comment thread
sirosen marked this conversation as resolved.
Outdated


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.

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.

.. tip::

You can read more about ``blurb`` in its
`repository <https://github.com/python/blurb>`__.

For more information on writing news entries,
see :ref:`"Updating NEWS and What's New in Python" <news-entry>`.

@StanFromIreland StanFromIreland Jun 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be higher, we don't want unnecessary news entries (it explains when you should(n't) add one).

@willingc willingc Jun 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps move this to line 124. Then, start a new paragraph for blurb-it.

@sirosen sirosen Jun 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to keep a link to the detailed reference at the end of this subsection if we can manage it. Keeping the ordering of the content consistent section to section makes the doc more navigable.
(If we can't maintain this ordering, that's okay, but I want to try.)

I can definitely edit the perhaps-too-pithy "many changes deserve a NEWS entry" up above.
Here's what's written in the linked doc:

Most changes made to the codebase deserve an entry in Misc/NEWS.d, except for the following:

  • documentation changes
  • test changes
  • strictly internal changes with no user-visible effects
  • changes that already have a NEWS entry
  • reverts that have not yet been included in any formal release (including alpha and beta releases)

If I reproduce this whole list, the quick-reference begins to wander into being a not-so-quick-reference.

Would this update be satisfactory?

-Many changes deserve a NEWS entry which documents what changed.
+Most user-visible changes, other than documentation changes,
+deserve a NEWS entry which documents what changed.

@sirosen sirosen Jun 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concurrent comments!
I'm considering that Carol's suggestion maybe works for what I want, in that we maintain "Short Version, Deep Link, Short Version, Deep Link, ..." alternating structure.

So the possibility with that approach is something like...

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

To add a NEWS entry, add a new file in the Misc/NEWS.d/ directory.
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
repository <https://github.com/python/blurb>__.

For more information about how to create news entries, see
:ref:"How to add a NEWS entry" <crossref-I-need-to-add>.

@willingc willingc Jun 23, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this suggestion @sirosen. Thoughts @StanFromIreland?

@StanFromIreland StanFromIreland Jun 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems good, but we can drop the tip (and move it to the other section if it's not already there), "quick references" should ideally be succinct :-)

Additionally, I'd reword the second paragraph a little, like so:

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/>__.

We've generally discouraged manual creation as it complicates things for new contributors. Users who want to do so can see the instructions in the How to add a news entry section.


Create pull requests
--------------------

Create pull bequests on GitHub from your branches, on your fork, and make sure
Comment thread
sirosen marked this conversation as resolved.
Outdated
to put the relevant issue number in ``gh-NNNNNN``` format in the pull request title.
Comment thread
sirosen marked this conversation as resolved.
Outdated
For example:

.. code-block:: text

gh-12345: Fix some bug in spam module

See also, GitHub's documentation on `creating Pull Requests`_.
Comment thread
sirosen marked this conversation as resolved.
Outdated

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
Comment thread
sirosen marked this conversation as resolved.
Outdated

Work on your pull request
-------------------------

Make sure the
:ref:`continuous integration checks on your Pull Request are green <keeping-ci-green>` (successful).
Comment thread
sirosen marked this conversation as resolved.
Outdated

Read and respond to reviewer comments on your pull request.

See also, GitHub's documentation on `commenting on Pull Requests`_.
Comment thread
sirosen marked this conversation as resolved.
Outdated

.. note::

In order to keep the commit history intact, please avoid squashing or amending
Comment thread
sirosen marked this conversation as resolved.
Outdated
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.

.. _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
93 changes: 3 additions & 90 deletions index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
willingc marked this conversation as resolved.
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
----------------------------------
Expand Down
Loading