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 #33283117 | 📁 Comparing 09e61f7 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.

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.

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!

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?

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.

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

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.

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

willingc

Thanks @sirosen. I appreciate the effort.

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.

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 I would leave this note as is. macOS systems do not typically use .exe files so being explicit here reduces confusion.

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.

Co-authored-by: Stan Ulbrych <stan@python.org>

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

Comment thread getting-started/quick-reference.rst Outdated

StanFromIreland reviewed Jun 21, 2026

View reviewed changes

Comment thread getting-started/quick-reference.rst Outdated

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

Apply suggestions from code review

09e61f7

Co-authored-by: Stan Ulbrych <stan@python.org>


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

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!

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!

willingc Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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

edited

Loading

willingc Jun 24, 2026 •

edited

Loading