GeezerVison

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.

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.

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

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

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

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.

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

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.