Repository navigation
Publish the changelog as Atom and JSON Feed (1.13.89) - #32
Merged
Merged
Conversation
docs/changelog.atom (Atom 1.0) and docs/changelog.json (JSON Feed 1.1) hold every entry of the changelog. main() parses CHANGELOG.md once and hands the same entries to changelog.html and to both feeds. Each feed entry carries the article HTML of the page, so the feeds cannot drift. Each entry has its version, its date, its sections with their items, a summary and the client library versions it names. The JSON Feed keeps those parsed fields in a _livetennisapi object on each item. An entry's id is its anchor on the page, and its dates come from its heading. A rebuild writes the same bytes, so --check covers both files. The Atom feed follows the corrections log feed on livetennisapi.com. Ids are page anchors and dates are at 00:00Z. The feed has a self link, an alternate link, the author, the icon and the rights. Each entry has a plain text summary. The build now fails when the Atom feed breaks an RFC 4287 rule or the JSON Feed breaks a JSON Feed 1.1 rule. It also fails when an entry of the page is missing from a feed or differs in it. scripts/changelog_feeds.py holds the writers and the checks, with the standard library only. scripts/test_changelog_feeds.py runs them on the committed files and on broken copies. changelog.html and the docs home link both feeds in their head. The changelog header links them in its text, and the page JSON-LD lists them as encodings. llms.txt lists both URLs. truthcheck.sh exempts the feeds as it exempts the page, since both quote old quotas in dated entries. Fix: fifteen headings from 1.1.0 to 1.9.3 used an em dash. The page showed them as text inside the 1.9.4 entry. They now use a hyphen, and the build stops on a heading it cannot read. The page has 115 entries. The spec version moves to 1.13.89 with a changelog entry. Nothing on the wire changed.
A review found that the page formatted each line of an item on its own. Bold or code that wrapped onto a second line was never closed. Six older entries showed raw asterisks and backticks, and the feeds repeated them. _md_block now formats an item once all its lines are in. Links written in angle brackets lose the brackets. The parity check used to compare the body HTML with itself, in effect. It now reads each entry's sections back from the page's HTML and compares them with the JSON Feed. Every field the two feeds share must also match between them, and the Atom content must be type html. The feed parse follows _md_block line for line. A repeated section stays two sections, so a note between them keeps its place. Notes now sit in their section. A heading with a bracketed version that is not an entry heading stops the build at any level. The Atom checker covers more of RFC 4287. Text and html constructs may not hold child elements, content may name a media type, and a person has one uri at most. A source counts for the author rule only when it has an author, and a category scheme must be an IRI. The JSON Feed checker now accepts author and checks attachments. A version above the newest published version of a client is a runtime, not the client, so "Python 3.12.4" no longer counts. llms.txt describes the _livetennisapi object that the feed's about link points to.
A second review found two client versions the feeds left out. 1.13.88 names JavaScript 1.10.3 and then says what failed in 1.10.2. 1.13.63 names livetennisapi-ai 1.1.0 and then says "until 1.2.1". A bare version now counts for the client named just before it in the same item, when it has that version's major number. Those two are the only versions this adds. An autolink inside bold, as in "**See <https://example.com>**", broke the build. The URL match ran on into the closing asterisks. Autolinks are now linked before md_inline sees the rest of the line. Entry headings must carry a version of the form x.y.z. The IRI check refuses a % that does not start a hex escape. Atom content with a src must be empty and give a media type. JSON Feed content_text must be a string, and the feeds must not carry it next to content_html. The parity check also reads the version and date shown in each heading. The build checks that the docs home links both feeds. A summary now holds the first two items and says how many more there are. JSON Feed describes a summary as a sentence or two, and the whole entry is in the content.
A third review replayed the feed discovery of NetNewsWire 7.3 on the docs home. It skips JSON Feed links and ranked openapi.json above the Atom feed, so subscribing to the home page picked the spec. Both feed links now come straight after the canonical link, Atom first. A version heading written without ## and underlined on the next line was dropped from all three outputs. A bracketed version and a dash at the start of a line now stops the build. So does a version that is not x.y.z. An autolink inside a code span stays literal text, in the feeds as on the page. HTML comments are removed before the page is compared with the feeds or searched for feed links. Dates with an offset past 23:59 fail the checks, and so does an extension name with a dot. "The Python client to 1.8.0" now counts as a client version. A bare version right after spec, API or changelog never does. The feeds came out the same.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an Atom feed and a JSON Feed of the changelog, so a developer or a tool can follow new versions of the spec.
Supersedes #16, which is based on an older main and now conflicts.
What changes
docs/changelog.atom(Atom 1.0) anddocs/changelog.json(JSON Feed 1.1) hold all 115 entries.main()parsesCHANGELOG.mdonce and passes the same entries tochangelog.htmland to both feeds._livetennisapiobject on each item, andllms.txtdescribes that object.changelog.html#v1.13.88. Its dates come from its heading. A rebuild writes the same bytes, so--checkcovers both files.changelog.htmland the docs home link both feeds in their head, Atom first. On the docs home they come before the OpenAPI links, so a reader that picks one feed picks the changelog. The changelog header links them in its text, and its JSON-LD lists them as encodings.llms.txtlists both URLs.truthcheck.shexempts the feeds as it exempts the page. Both quote old quotas in dated entries.Fixes on the page
Checks
scripts/changelog_feeds.pyand use the standard library only, so CI needs nothing new.python -m unittest scripts/test_changelog_feeds.pyruns 26 tests. They check the committed feeds and break copies to show each rule catches its fault.build_reference.py --check,truthcheck.sh, both unittest files and Redocly lint pass.The spec version moves to 1.13.89 with a changelog entry. Nothing on the wire changed.