Skip to content

Infra: Move release dates from RSTs to JSON #4314

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.

Sign up for GitHub

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Infra: Move release dates from RSTs to JSON #4314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .coveragerc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# .coveragerc to control coverage.py

[report]
# Regexes for lines to exclude from consideration
exclude_also =
if TYPE_CHECKING:
45 changes: 42 additions & 3 deletions pep_sphinx_extensions/pep_processor/html/pep_html_translator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,32 @@
from __future__ import annotations

from typing import TYPE_CHECKING
import datetime as dt
import json

from docutils import nodes
import sphinx.writers.html5 as html5
from docutils import nodes

TYPE_CHECKING = False
if TYPE_CHECKING:
from sphinx.builders import html


def create_release_list(release_dates: dict[str, str]) -> str:
releases = []
for version, date in release_dates.items():
if version.endswith("beta 1"):
beta = " (No new features beyond this point.)"
else:
beta = ""
date = dt.datetime.strptime(date, "%Y-%m-%d").date()
new = f"{version}: {date.strftime('%A, %Y-%m-%d')}{beta}"
releases.append(new)

release_list = "\n".join(f"<li>{release}" for release in releases)

return f'<ul class="simple">{release_list}</ul>'
Copy link
Member

Choose a reason for hiding this comment

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

It's better to do this in the AST rather than the writer (e.g HTML)



class PEPTranslator(html5.HTML5Translator):
"""Custom RST -> HTML translation rules for PEPs."""

Expand Down Expand Up @@ -46,13 +64,34 @@
return True

def visit_paragraph(self, node: nodes.paragraph) -> None:
"""Remove <p> tags if possible."""
"""Remove <p> tags if possible and add dates to release PEPs."""

if self.should_be_compact_paragraph(node):
self.context.append("")
else:
self.body.append(self.starttag(node, "p", ""))
self.context.append("</p>\n")

title = None
for title_node in self.document.findall(nodes.title):
title = title_node.astext()
break

Check warning on line 78 in pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py#L75-L78 

Added lines #L75 - L78 were not covered by tests

if title.endswith("Release Schedule"):
version = title.split()[4]

Check warning on line 81 in pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py#L80-L81 

Added lines #L80 - L81 were not covered by tests

for i, child in enumerate(node.children):
if isinstance(child, nodes.Text):
text = child.astext()
if text in ("[ACTUAL]", "[EXPECTED]"):
with open("peps/release-dates.json", encoding="utf-8") as f:
release_dates = json.load(f)

Check warning on line 88 in pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py#L83-L88 

Added lines #L83 - L88 were not covered by tests

category = text[1:-1].lower()
text = create_release_list(release_dates[version][category])

Check warning on line 91 in pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py#L90-L91 

Added lines #L90 - L91 were not covered by tests

node.children[i] = nodes.raw("", text, format="html")

Check warning on line 93 in pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

View check run for this annotation

Codecov / codecov/patch

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py#L93 

Added line #L93 was not covered by tests

def depart_paragraph(self, _: nodes.paragraph) -> None:
"""Add corresponding end tag from `visit_paragraph`."""
self.body.append(self.context.pop())
Expand Down
30 changes: 30 additions & 0 deletions pep_sphinx_extensions/tests/pep_processor/html/test_pep_html_translator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
from pep_sphinx_extensions.pep_processor.html import pep_html_translator


def test_create_release_list():
# Arrange
release_dates = {
"3.14.0 alpha 7": "2025-04-08",
"3.14.0 beta 1": "2025-05-06",
"3.14.0 beta 2": "2025-05-27",
"3.14.0 beta 3": "2025-06-17",
"3.14.0 beta 4": "2025-07-08",
"3.14.0 candidate 1": "2025-07-22",
"3.14.0 candidate 2": "2025-08-26",
"3.14.0 final": "2025-10-07",
}

# Act
result = pep_html_translator.create_release_list(release_dates)

# Assert
assert result.splitlines() == [
'<ul class="simple"><li>3.14.0 alpha 7: Tuesday, 2025-04-08',
"<li>3.14.0 beta 1: Tuesday, 2025-05-06 (No new features beyond this point.)",
"<li>3.14.0 beta 2: Tuesday, 2025-05-27",
"<li>3.14.0 beta 3: Tuesday, 2025-06-17",
"<li>3.14.0 beta 4: Tuesday, 2025-07-08",
"<li>3.14.0 candidate 1: Tuesday, 2025-07-22",
"<li>3.14.0 candidate 2: Tuesday, 2025-08-26",
"<li>3.14.0 final: Tuesday, 2025-10-07</ul>",
]
18 changes: 2 additions & 16 deletions peps/pep-0745.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,25 +35,11 @@ in a 12-month release cadence between feature versions, as defined by

Actual:

- 3.14 development begins: Wednesday, 2024-05-08
- 3.14.0 alpha 1: Tuesday, 2024-10-15
- 3.14.0 alpha 2: Tuesday, 2024-11-19
- 3.14.0 alpha 3: Tuesday, 2024-12-17
- 3.14.0 alpha 4: Tuesday, 2025-01-14
- 3.14.0 alpha 5: Tuesday, 2025-02-11
- 3.14.0 alpha 6: Friday, 2025-03-14
[ACTUAL]

Expected:

- 3.14.0 alpha 7: Tuesday, 2025-04-08
- 3.14.0 beta 1: Tuesday, 2025-05-06
(No new features beyond this point.)
- 3.14.0 beta 2: Tuesday, 2025-05-27
- 3.14.0 beta 3: Tuesday, 2025-06-17
- 3.14.0 beta 4: Tuesday, 2025-07-08
- 3.14.0 candidate 1: Tuesday, 2025-07-22
- 3.14.0 candidate 2: Tuesday, 2025-08-26
- 3.14.0 final: Tuesday, 2025-10-07
[EXPECTED]

Subsequent bugfix releases every two months.

Expand Down
23 changes: 23 additions & 0 deletions peps/release-dates.json
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

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

Is the idea for this file to replace e.g. the devguide one, or be used to build the version switcher on d.p.o? If so, I think having the 'official' location be the PEPs repo feels a bit hidden. The devguide feels 'best' as it is non-versioned, but equally we get complaints that that is non-obvious.

If we do want a single-data-file-of-truth, I would probably suggest putting all of the devguide fields into this one, as otherwise it gets more complex/annoying with multiple slightly different files describing roughly the same thing.

On a practicalities level, I'd suggest using TOML, which has both support for dates, comments, trailing commas, etc and slightly nicer formatting for human consumption. E.g.:

[[3.14]]
stage = "development begins"
date = 2024-05-08
actual = true

[[3.14]]
# ...

[[3.14]]
stage = "beta 1"
date = 2025-05-06
actual = false

A

Copy link
Member Author

Choose a reason for hiding this comment

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

Is the idea for this file to replace e.g. the devguide one, or be used to build the version switcher on d.p.o?

Yes, I'm primarily thinking of replacing the devguide one.

If so, I think having the 'official' location be the PEPs repo feels a bit hidden. The devguide feels 'best' as it is non-versioned, but equally we get complaints that that is non-obvious.

My thinking of it being here is because this is where the equivalent release PEPs are. When the 3.15 PEP is added, it can be done right here in both RST and data file. This is the PEPs spec repo, this is where you come for the release dates now, it feels right the definitive release dates are retained in the same place.

TOML, possibly, although that would make it harder to use for example in JavaScript.

Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"3.14": {
"actual": {
"3.14 development begins": "2024-05-08",
"3.14.0 alpha 1": "2024-10-15",
"3.14.0 alpha 2": "2024-11-19",
"3.14.0 alpha 3": "2024-12-17",
"3.14.0 alpha 4": "2025-01-14",
"3.14.0 alpha 5": "2025-02-11",
"3.14.0 alpha 6": "2025-03-14"
},
"expected": {
"3.14.0 alpha 7": "2025-04-08",
"3.14.0 beta 1": "2025-05-06",
"3.14.0 beta 2": "2025-05-27",
"3.14.0 beta 3": "2025-06-17",
"3.14.0 beta 4": "2025-07-08",
"3.14.0 candidate 1": "2025-07-22",
"3.14.0 candidate 2": "2025-08-26",
"3.14.0 final": "2025-10-07"
}
}
}