Move the "quick reference" to a dedicated page by sirosen · Pull Request #1838 · python/devguide

sirosen · 2026-06-13T23:45:07Z

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.

closes #1837

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 python#1837, the page is placed in Getting Started but after the setup guide.

read-the-docs-community · 2026-06-13T23:46:10Z

Documentation build overview

📚 CPython devguide | 🛠️ Build #33253361 | 📁 Comparing 1a76f5e against latest (24065f9)

🔍 Preview build

7 files changed · + 1 added · ± 6 modified

+ Added

getting-started/quick-reference/index.html

± Modified

StanFromIreland · 2026-06-14T08:20:12Z

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


I don't think this makes sense now, we redirect people back to the page they've just read?

This doesn't go back to the home page. It goes to a detailed page about git etc.

I was not referring to the home page. As @sirosen noted in the PR description:

the page is placed in Getting Started but after the setup guide.

We're sending them back to the page just before.

I see, sorry. So we should move this up in the contents.

I think we can rename it to "Overview," and make it an index for the overall quite long "Getting started" section. Additionally, we could merge it with the other Quick Guide, and add a link to the Where to get help at the end. Some of the steps could also use additional links to the more detailed sections.

I would love to see this page be minimalist visually and cheatsheet-like. I think @StanFromIreland is on the right track though "Overview" feels too broad.

Additionally, we could merge it with the other Quick Guide, and add a link to the Where to get help at the end.

Oh no! I didn't realize that there was another, other-other quick reference. 😂

My initial reaction is that I think these should be combined, still in the form of a new page.

I need to do some careful cross-comparison of the content and see if such a change is feasible in practice, without this PR growing too large in scope.

StanFromIreland · 2026-06-14T08:20:40Z

+
+         PCbuild\build.bat -e -d
+
+   See also :ref:`more detailed instructions <compiling>`,


All of the above steps should have been completed by the time they reach this page, so we don't quite need them.

I think all the "see also" items could go later in this document. Perhaps in a "Dive deeper" section.

StanFromIreland · 2026-06-14T08:22:07Z

+
+         .\python.bat -m test -j3
+
+5. Create a new branch where your work for the issue will go, for example::


This section is duplicated by our other "Quick guide".

Steps 5-7 could be their own section or their own page. Keep 1-4 as build from source and run tests.

hugovk · 2026-06-14T08:53:16Z

+.. _quick-reference:
+
+===============
+Quick Reference


Use sentence case for headers:

https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change

Quick Reference

Quick reference

May make sense to be more specific on the title of this doc. Quick reference feels too broad. Something that evokes the original purpose checklist/cheatsheet would make more sense.

We could put it at or near the end of Getting Started, under the name "Workflow cheatsheet".

It would read logically that way, and that name is harmonious with the element of this doc that I'm trying to preserve.

willingc

@sirosen Thanks for following up on the issue that you filed. I think you have some good points. The devguide has evolved quite a bit over the past decade and simplifying the index page makes good sense.

willingc · 2026-06-15T15:48:37Z

+.. _quick-reference:
+
+===============
+Quick Reference


May make sense to be more specific on the title of this doc. Quick reference feels too broad. Something that evokes the original purpose checklist/cheatsheet would make more sense.

willingc · 2026-06-15T15:51:33Z

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


I would love to see this page be minimalist visually and cheatsheet-like. I think @StanFromIreland is on the right track though "Overview" feels too broad.

willingc · 2026-06-15T15:53:02Z

+
+         PCbuild\build.bat -e -d
+
+   See also :ref:`more detailed instructions <compiling>`,


I think all the "see also" items could go later in this document. Perhaps in a "Dive deeper" section.

willingc · 2026-06-15T15:54:43Z

+
+         .\python.bat -m test -j3
+
+5. Create a new branch where your work for the issue will go, for example::


Steps 5-7 could be their own section or their own page. Keep 1-4 as build from source and run tests.

willingc · 2026-06-15T15:57:07Z

-Quick reference
---------------
-
-Here are the basic steps needed to get set up and open a pull request.


When moving these items to a new page, let's keep the Quick reference title and have an admonition of where the content has moved and why (for approx. 6 months).

We can add a little deferred Javascript redirect for the anchor, e.g.:

function redirectAnchor() { const anchor = window.location.hash.slice(1); if (!anchor || document.getElementById(anchor)) { return; } if (anchor !== "anchor") { return; } window.location.replace(new URL("redirect", window.location.href).href); } redirectAnchor();

I like the idea, but have two reasons I don't want to pursue it at the moment.

Reusability. We probably don't want to do a bespoke bit of JS each time we do a redirect.

I'd like us to pack this idea up to be reusable. I think the redirector you recently proposed for CPython docs was similar -- but I did see that not everyone agreed on that.

Scope creep. This will already end up being a larger PR than I intended.

When I circle back on this, I'll be moving more pieces around and actually changing some content to address feedback. I worry that adding in new code for the site may make this harder to merge, so I'd like to stick strictly to content edits.

(I can definitely take feedback if there's broad agreement that everyone really wants us to add redirectAnchor() right here! But I'm hesitant to embrace the idea without more signal.)

OK, let's do this. Let's remove and if folks get confused, we can always add this later. Thanks @sirosen.

FWIW, I did include a "breadcrumb" per your other suggestion. It's now way at the bottom of this diff, but it's short-and-sweet:

.. note:: 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>`.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

The idea of making this section not be first is somewhat at odds with the fact that it needs to link to the first page under Getting Started. It would work to move it to the end, or to the beginning. The beginning seems to be the "least surprise" choice for doc readers and contributors.

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.

Instead of a duplicate guide, we can now link to the canonical quick reference doc.

In the index, ensure that anyone going to the old quick-reference documentation will find a short explanatory note and a link to the new, rehomed quick-reference.

sirosen · 2026-06-21T03:49:20Z

I've just pushed a few changes that attempt to address all of the outstanding review comments.

It seemed to me that I had to choose: (A) double down on this as a "quick start" or "quick reference" and move it to the start of Getting Started (B) adjust phrasing to make this a "cheat sheet" and move it to the end.
I looked at both, thinking I wanted (B), but (A) was much easier to achieve. I kept the name the same, "quick reference", although I somewhat agree with Carol's thought that the name is a bit vague and imperfect -- I just didn't come up with a better one.
I also broke it down into sections, rather than keeping it as a list. It's still very short in content, but it looks bulkier with the section headings. I think that with sections the page makes more sense, as it crosses several topic areas.
Each section links deeply to the matching place in Getting Started (or testing docs, for the testing item).
I eliminated the PR "quick guide" and made sure that the content from there about opening PRs is carried over. A very small amount of content from the start of that section is lost (I noted this in Discord chat; potentially I could file an issue to restore it?).

StanFromIreland · 2026-06-21T09:09:22Z

+   git clone https://github.com/<your_username>/cpython
+   cd cpython
+
+We recommend also setting up ``pre-commit``::


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

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

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

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.

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

StanFromIreland · 2026-06-21T09:09:48Z

+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j8


Why are we limiting to 8?

Some number is better than none, easy to adjust once you know a number goes there, and arbitrary selection based on market hardware: #1545

If $(nproc) can fail then why not leave it up to make and pass -j (I'm not sure if that works over on macOS, I presume it would be the same as on Linux), it should use all available then.

It depends on the make command. With GNU make:

-j [jobs], --jobs[=jobs] Specifies the number of jobs (commands) to run simultaneously. If there is more than one -j option, the last one is effective. If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously.

"Don't limit" isn't the same as "use all available".

I see that Hugo 👍'ed the comment below about switching to -j0 for the test command.
I'm unclear, should I apply a change here as well?

I'm not familiar with the semantics of -j0 (I'm guessing that it means unlimited job slots?); I've always either used no argument or used a positive integer.

I have no strong opinion about this detail. -j 8 reads very reasonably to me. -j 0 feels a little more obscure, but I don't hate it.

Unlike python -m test, make does not understand -j0.

The Mac/BSD equivalent for make -j$(nproc) is make -j $(sysctl -n hw.logicalcpu). Not something you'd want to type in, but perhaps people copy/paste from here?

Let's use @encukou's suggestion make -j $(sysctl -n hw.logicalcpu) or make -j 8. My M2 on Tahoe returns 8. I slightly prefer Petr's suggestion since it will use the resources available on the user's system.

Suggested change

./configure --config-cache --with-pydebug && make -j8

./configure --config-cache --with-pydebug && make -j$(sysctl -n hw.logicalcpu)

I don't have a Mac or Mac-knowledge to test, but I think using all available is better then picking numbers we'll have to update in the future.

StanFromIreland · 2026-06-21T09:12:15Z

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


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

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

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.

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

I like this suggestion @sirosen. Thoughts @StanFromIreland?

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.

StanFromIreland · 2026-06-21T09:13:39Z

+
+   .. code-block:: shell
+
+      ./python.exe -m test -j8


Similarly here, why the difference? We can pass -j0 here.

Let's be consistent with the number. We could add a note that for most recent macs 8 would be fine.

Suggested change

./python.exe -m test -j8

./python.exe -m test -j0

hugovk · 2026-06-21T09:54:04Z

+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j8


It depends on the make command. With GNU make:

-j [jobs], --jobs[=jobs] Specifies the number of jobs (commands) to run simultaneously. If there is more than one -j option, the last one is effective. If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously.

"Don't limit" isn't the same as "use all available".

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

willingc

Thanks @sirosen. I appreciate the effort.

willingc · 2026-06-22T17:03:20Z

+
+   .. code-block:: shell
+
+      ./python.exe -m test -j8


Let's be consistent with the number. We could add a note that for most recent macs 8 would be fine.

willingc · 2026-06-22T17:04:35Z

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


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

willingc · 2026-06-22T17:05:38Z

-Quick reference
---------------
-
-Here are the basic steps needed to get set up and open a pull request.


OK, let's do this. Let's remove and if folks get confused, we can always add this later. Thanks @sirosen.

StanFromIreland · 2026-06-23T16:04:16Z

+
+   .. code-block:: shell
+
+      ./python -m test -j3


Suggested change

./python -m test -j3

./python -m test -j0

StanFromIreland · 2026-06-23T16:04:21Z

+
+   .. code-block:: shell
+
+      ./python.exe -m test -j8


Suggested change

./python.exe -m test -j8

./python.exe -m test -j0

StanFromIreland · 2026-06-23T16:04:30Z

+
+   .. code-block:: dosbatch
+
+      .\python.bat -m test -j3


Suggested change

.\python.bat -m test -j3

.\python.bat -m test -j0

StanFromIreland · 2026-06-23T16:06:32Z

+   .. note::
+      :ref:`Most <mac-python.exe>` macOS systems use
+      :file:`./python.exe` in order to avoid filename conflicts with
+      the ``Python`` directory.


Suggested change

.. note::

:ref:`Most <mac-python.exe>` macOS systems use

:file:`./python.exe` in order to avoid filename conflicts with

the ``Python`` directory.

Seeing as this is a quick reference, we can skip such things where it's "on macOS by default."

StanFromIreland · 2026-06-23T16:13:25Z

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


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.

StanFromIreland · 2026-06-23T16:14:55Z

+Make sure the
+:ref:`continuous integration checks on your Pull Request are green <keeping-ci-green>` (successful).


Suggested change

Make sure the

:ref:`continuous integration checks on your Pull Request are green <keeping-ci-green>` (successful).

Make sure the :ref:`continuous integration checks on your Pull

Request are green <keeping-ci-green>` (successful).

(FYI you can wrap inside a :ref:)

StanFromIreland reviewed Jun 14, 2026

View reviewed changes

hugovk reviewed Jun 14, 2026

View reviewed changes

willingc reviewed Jun 15, 2026

View reviewed changes

sirosen and others added 5 commits June 17, 2026 18:26

Change "Quick reference" to sentence-case

543e002

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Replace the PR quickguide with a link

5e7e09e

Instead of a duplicate guide, we can now link to the canonical quick reference doc.

Restore a "continuity" quick-reference section

86f942c

In the index, ensure that anyone going to the old quick-reference documentation will find a short explanatory note and a link to the new, rehomed quick-reference.

StanFromIreland reviewed Jun 21, 2026

View reviewed changes

hugovk reviewed Jun 21, 2026

View reviewed changes

Apply suggestions from code review

1a76f5e

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

willingc approved these changes Jun 22, 2026

View reviewed changes

willingc approved these changes Jun 23, 2026

View reviewed changes

StanFromIreland reviewed Jun 23, 2026

View reviewed changes


		PCbuild\build.bat -e -d

		See also :ref:`more detailed instructions <compiling>`,


		.\python.bat -m test -j3

		5. Create a new branch where your work for the issue will go, for example::


		.. code-block:: shell

		./configure --config-cache --with-pydebug && make -j8

		Make sure the
		:ref:`continuous integration checks on your Pull Request are green <keeping-ci-green>` (successful).

Uh oh!

Conversation

sirosen commented Jun 13, 2026

Uh oh!

read-the-docs-community Bot commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen commented Jun 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

read-the-docs-community Bot commented Jun 13, 2026 •

edited

Loading

encukou Jun 23, 2026 •

edited

Loading