Skip to content

Add python-releases.toml #4331

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.

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

Open
wants to merge 36 commits into
base: main
Choose a base branch
from
Open

Conversation

AA-Turner
Copy link
Member

@AA-Turner AA-Turner commented Mar 29, 2025

Inspired by #4314, this PR adds a transcription of every Python release since version 1.6 into a single TOML document, python-releases.toml. This is intended to serve as a single, centralised, machine-readable record of Python's release history (and future).

From this, we automatically generate a release-cycle.json file as part of the build process, to be published on peps.python.org. This replaces the version in the devguide.

The TOML document is used to (re-)generate the release schedules contained in release PEPs, initially starting with those for Python 3.8 to 3.14. The authoritative record and history remains the release PEP.

Some releases may need optional annotations or notes, which I have filled in for Python 3.8 and 3.9, but not yet back-filled.

Open questions:

  • Any better ideas for a filename than python-releases.toml?
  • Should the file live at the top level, or in the a subdirectory (as at present)?
  • Any better ideas for the metadata field names? I'm not a great fan of start-of-development and end-of-bugfix, as all the others can be said aloud as "The {first release / feature freeze / end of life} is/was on {date}".
  • Are the release managers for Pythons 1.6-2.2 correct?

A


📚 Documentation preview 📚: https://pep-previews--4331.org.readthedocs.build/
📚 Documentation preview 📚: https://pep-previews--4331.org.readthedocs.build/release-cycle.json

@AA-Turner AA-Turner added the meta Related to the repo itself and its processes label Mar 29, 2025
Copy link
Member

@hugovk hugovk left a comment

Choose a reason for hiding this comment

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

Partial review:

From this, we automatically generate a release-cycle.json file as part of the build process, to be published on peps.python.org. This replaces the version in the devguide.

Can we make all the data in the TOML also available in the JSON?

JSON is more universally supported, and we should make this data as widely usable as possible.

We don't necessarily need the JSON here to be an exact copy of the old devguide one; as long as the devguide can read the data it needs from this JSON to construct the diagram and tables.

Open questions:

  • Any better ideas for a filename than python-releases.toml?

Fine by me.

  • Any better ideas for the metadata field names? I'm not a great fan of start-of-development and end-of-bugfix, as all the others can be said aloud as "The {first release / feature freeze / end of life} is/was on {date}".

We could use the same names as the https://endoflife.date/ API.

The alpha https://endoflife.date/api/python.json currently uses:

  • releaseDate - initial release
  • support - end of bugfix
  • eol - end of security support / life

Or the WIP v1 API (endoflife-date/endoflife.date#2080), https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/products/python uses:

  • date - initial release
  • eoasFrom - end of bugfix (end of active support)
  • eolFrom - end of security support / life

AA-Turner added 4 commits May 2, 2025 23:05
# Conflicts:
#	peps/pep-0596.rst
#	peps/pep-0619.rst
#	peps/pep-0664.rst
#	peps/pep-0693.rst
#	peps/pep-0719.rst
Copy link
Contributor

@m-aciek m-aciek left a comment

Choose a reason for hiding this comment

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

I've left some minor comments.

The centralised file is 3400 lines long. I wonder, would it be possible to get all release metadata from the release PEPs, after enforcing the data structure using Sphinx/docutils features? This way the source of truth would be PEPs with machine-extractable data, and the data would be much easier to maintain/add. Then JSON/TOML would be generated in CI or locally automatically from the PEPs. Automatic script would go through all informational PEPs with release topic and look for the metadata. What do you think?

@AA-Turner
Copy link
Member Author

I wonder, would it be possible to get all release matadata from the release PEPs, after enforcing the data structure using Sphinx/docutils features?

We could, but this would have a couple of considerations. Most importantly, we would need to change every previous release PEP, and this wouldn't easily permit going back before 1.6 if we wanted to record the metadata for 0.9-1.5.

I wouldn't be entirely opposed to this, though, as it preserves the nice quality that the PEPs remain the authoritative source for release information.

A

# Conflicts:
#	peps/pep-0596.rst
#	peps/pep-0619.rst
#	peps/pep-0664.rst
#	peps/pep-0719.rst
Copy link
Member

@hugovk hugovk left a comment

Choose a reason for hiding this comment

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

Summary of discussion with Adam at EuroPython sprints:

I'd like us to provide the full data as JSON, so it's more widely available, for example, when using JavaScript.

I don't mind the source data being in TOML or JSON. It is extra work to convert from TOML to JSON, but that shouldn't be too hard, and TOML is a bit nicer to edit by hand.

I also don't mind if we provide the same smaller release-cycle.json file for the devguide to consume, or update the devguide to read the full one. Adam has preference for the small file.

@AA-Turner AA-Turner marked this pull request as ready for review July 20, 2025 15:52
@AA-Turner AA-Turner requested review from Yhg1s, pablogsal, ambv, CAM-Gerlach and a team as code owners July 20, 2025 15:52
Comment on lines +78 to +82
release_cycle = create_release_cycle()
app.outdir.joinpath('release-cycle.json').write_text(release_cycle, encoding="utf-8")

release_json = create_release_json()
app.outdir.joinpath('python-releases.json').write_text(release_json, encoding="utf-8")
Copy link
Member

Choose a reason for hiding this comment

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

Let's stick these next to https://peps.python.org/api/peps.json so we can (later) document them at https://peps.python.org/api/

Suggested change
release_cycle = create_release_cycle()
app.outdir.joinpath('release-cycle.json').write_text(release_cycle, encoding="utf-8")
release_json = create_release_json()
app.outdir.joinpath('python-releases.json').write_text(release_json, encoding="utf-8")
release_cycle = create_release_cycle()
app.outdir.joinpath('api/release-cycle.json').write_text(release_cycle, encoding="utf-8")
release_json = create_release_json()
app.outdir.joinpath('api/python-releases.json').write_text(release_json, encoding="utf-8")

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't think this is right. The releases as machine-readable data have nothing to do with the "API" of the PEPs website, to the extent that such a thing exists. I don't see a reasonable reason not to have the files at the root, it won't conflict with anything & it's a shorter link. If you do want to put the JSON files in a subdirectory though, let's use a more appropriate folder name (e.g. /python-releases/{...}.json).

Copy link
Member

Choose a reason for hiding this comment

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

The releases as machine-readable data have nothing to do with the "API" of the PEPs website, to the extent that such a thing exists.

The data is here, it's coming from the PEPs website; it's data from the release PEPs.

We're precomputing the data to create a read-only API served via static JSON. This is a common thing to do.

I don't see a reasonable reason not to have the files at the root

So we can document them via https://peps.python.org/api/

it's a shorter link

This data will be mostly read by machines, an extra 4 characters is no problem.

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree it would make sense to document the files. I still think that peps.python.org/api/ is the wrong place, though. My preference would be to keep the files at the root, but I would also be OK with a clearly-named folder like /python-releases/ or similar.

@AA-Turner
Copy link
Member Author

AA-Turner commented Aug 7, 2025

Thanks for the review, I've responded to the comments (& fixed the formatting where it was wrong, thank you for pointing it out). I've also added the 1.6 alphas and corrected a few other dates/added more supporting links. I've updated the release manager for 1.6--2.1 to by Hylton & GvR, it seems that the current RM model didn't properly come into being until 2.1.

Lint failure is the ongoing pre-commit-uv problems.

A

Comment on lines +78 to +82
release_cycle = create_release_cycle()
app.outdir.joinpath('release-cycle.json').write_text(release_cycle, encoding="utf-8")

release_json = create_release_json()
app.outdir.joinpath('python-releases.json').write_text(release_json, encoding="utf-8")
Copy link
Member

Choose a reason for hiding this comment

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

The releases as machine-readable data have nothing to do with the "API" of the PEPs website, to the extent that such a thing exists.

The data is here, it's coming from the PEPs website; it's data from the release PEPs.

We're precomputing the data to create a read-only API served via static JSON. This is a common thing to do.

I don't see a reasonable reason not to have the files at the root

So we can document them via https://peps.python.org/api/

it's a shorter link

This data will be mostly read by machines, an extra 4 characters is no problem.

@AA-Turner
Copy link
Member Author

Python 3.9 failures are new and still related to the pre-commit-uv problems: tox-dev/pre-commit-uv#70

A

@hugovk
Copy link
Member

hugovk commented Aug 9, 2025

Python 3.9 failures are new and still related to the pre-commit-uv problems: tox-dev/pre-commit-uv#70

A

Now fixed and passes with a rebuild.

@AA-Turner AA-Turner requested a review from hugovk August 12, 2025 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
meta Related to the repo itself and its processes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants