Skip to content
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

Add release cycle chart #67

Open
hugovk opened this issue Nov 7, 2022 · 5 comments
Open

Add release cycle chart #67

hugovk opened this issue Nov 7, 2022 · 5 comments
Labels
discussion enhancement New feature or document request

Comments

@hugovk
Copy link
Member

hugovk commented Nov 7, 2022

In 2019 Dustin Ingram made this chart of the Python release cycle: https://python-release-cycle.glitch.me/

image

Jeff Triplett and I have forked to make one for Django and Drupal respectively. It's a simple static site: some HTML, JS and CSS using a Gantt chart from Google Charts:

Dustin recently asked:

Hugo, do you think there's any appetite for putting this in more official docs or web properties somewhere? I think there was talk about that at some point but never saw it happen.

I think it would be good, it has come up before a couple of times:

Options

If so, we have a number of options.

We could:

Proof of concept

For option two, I made a proof of concept using https://github.com/mgaitan/sphinxcontrib-mermaid to render a Gantt chart on the devguide: https://hugovk-devguide.readthedocs.io/en/mermaid/versions/

image

Right now it duplicates the dates, but once python/devguide#884 is merged, we could generate them from the CSV.

Further

Let's discuss in today's docs community meeting.

@hugovk hugovk added enhancement New feature or document request discussion labels Nov 7, 2022
@hugovk
Copy link
Member Author

hugovk commented Nov 10, 2022

Notes from the meeting:

We thought it would be nice to have something like this on both https://python.org/downloads and https://devguide.python.org/versions. We'll start with the latter using the proof of concept (remembering the Diátaxis iterative model), wait for python/devguide#884 to be merged (now merged), then generate those CSV files and the Mermaid file from a JSON file.

I've made a start on this.

See also @encukou's python/devguide#884 (comment):

FWIW, I think the source should be a human-writable format, and we should generate a JSON for the machines to consume (like peps.python.org/api/peps.json). And we should tell people to expect the source format to change whenever we feel like it. (That'll need a Sphinx plugin, but if we want to move the formatting out of the tables, one will be needed anyway.)

@encukou Did you have a human-writable format did you have in mind? It also needs to be machine readable.

A flat, nicely-formatted JSON file should be easily human-writable? For example:

[
  {
    "cycle": "main",
    "pep": 693,
    "status": "features",
    "releaseManager": "Thomas Wouters",
    "releaseDate": "2023-10-02",
    "eol": "2028-10"
  },
  {
    "cycle": "3.11",
    "pep": 664,
    "status": "bugfix",
    "releaseManager": "Pablo Galindo Salgado",
    "releaseDate": "2022-10-24",
    "eol": "2027-10"
  },
...

@encukou
Copy link
Member

encukou commented Nov 10, 2022

Writing JSON is a pain.

Did you have a human-writable format did you have in mind? It also needs to be machine readable.

I helped add tomllib for this! (Well, acltually for Misc/stable_abi.toml – the same story). But depending on 3.11+ (or an external dependency) might not be appropriate.
My second choice is configparser/INI. See the PEP 518 table – most of INI's downsides don't apply if we don't care for third-party (non-python) tools, and if the schema is simple.

@merwok
Copy link
Member

merwok commented Nov 10, 2022

Link to pydotorg issue: python/pythondotorg#2066
For reference, original discussion about all this: endoflife-date/endoflife.date#711

@ezio-melotti
Copy link
Member

ezio-melotti commented Nov 10, 2022

Writing JSON is a pain.

If we use a format similar to the one @hugovk proposed it shouldn't be too bad: we will either have to update some dates here and there or copy/paste/update a section when a new release comes out.

If we use JSON it will also be easier for other people to consume it, if we don't we will either have to generate a JSON or they will have to add extra dependencies to handle toml/config files (or worse, parse them manually).

Also note that in python/pythondotorg#2066 also requested patch versions to be included (in the JSON).

@CAM-Gerlach
Copy link
Member

CAM-Gerlach commented Nov 10, 2022

In general, I'm strongly in favor of TOML over JSON for human-readable, and even more importantly human-writable format, and make heavy use of it as such. However, for this specific case, I believe practicality strongly outweighs purity here.

This use case is tightly constrained, to one very specific file, relatively short/simple file that we have full control of the format of, that is updated by a very small number of experienced people, in a highly constrained manner, and with updates being either tweaking one or a few existing values and (once a version/year) copy/pasting a new version block, so the practical downsides of JSON vs. TOML are minimized, whereas the former's greater simplicity and concision is maximized.

By contrast, generating JSON from TOML rather than simply using it as the source requires non-trivial complexity for users, contributors and maintainers of the devguide, a cost which seems likely to equal or outweigh any benefit for this particular case, as others have mentioned.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
discussion enhancement New feature or document request
Projects
None yet
Development

No branches or pull requests

5 participants