Provide MD checklists for the changelog

[Johennes]

Fixes: #1682

This changes /changelog to be a section and adds a separate output format to provide Markdown checklists under /changelog/$VERSION/checklist.md.

Example:

• HTML: https://pr1937--matrix-spec-previews.netlify.app/changelog/v1.11/
• MD: https://pr1937--matrix-spec-previews.netlify.app/changelog/v1.11/checklist.md

I've also added links to the checklists in each version's header table.

Since each version's changelog has a separate page now, inlining all changelogs on the index page seemed superfluous. Similarly, having the index page only list historical spec versions felt odd. Therefore, I've moved the info about historical versions to its own page and made the index page redirect to the latest version's changelog page.

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr1937--matrix-spec-previews.netlify.app

[zecakeh]

It seems strange to me to have the same content twice in "Changelog" and in the different versions. This also complicates the rendering because the levels of the headings should be different in both cases.

Maybe clicking on "Changelog" could just open the latest version?

[Johennes]

Maybe clicking on "Changelog" could just open the latest version?

I like that, yeah. I was worried that changing that page would break existing links. However, I'm now realizing any existing link (such as https://spec.matrix.org/v1.11/changelog/#internal-changestooling) would point into a historic spec version anyway. So this seems like a non-issue. 🤦

[Johennes]

Maybe clicking on "Changelog" could just open the latest version?

Have made it so.

[Johennes]

I've removed this entirely because the added info felt superfluous. Every changelog lists changes made since the last release and the version is apparent via the URL and page heading.

[zecakeh]

Thanks, it looks good. I like that when we hover a version in the sidebar, there's the full title that appears.

I am not a fan of the redirect on the "Changelog" page, I would prefer for the link to be the correct one, but I guess there is no simple way to do that with Hugo.

[Johennes]

I am not a fan of the redirect on the "Changelog" page, I would prefer for the link to be the correct one, but I guess there is no simple way to do that with Hugo.

Yeah, it's not pretty, especially because the index page briefly flashes before redirecting. Maybe we could render the latest version's changelog inline on the index page instead? That would effectively make /changelog a shortcut for /changelog/$latest.

[richvdh]

we could add something like:

manualLinkRelRef: unstable.md

to the front matter of content/changelog/_index.html, but it would need maintaining during releases. (We could hack the generate-changelog.sh script to update it?)

Or we could add more intelligence to layouts/partials/sidebar-tree.html to handle this case?

This is probably fine for now, and we could improve it in a future PR.

[richvdh]

I'm inclined to merge this if there are no pressing objections from other SCT members.

[richvdh]

(I like breaking the changelog up into pages, irrespective of any benefits from the checklist)

[clokep]

I'm a fan of the output, but haven't checked the implementation.

[richvdh]

Let's ship it then

[anoadragon453]

This appears to have generated broken links on the live site: https://github.com/matrix-org/matrix-spec/actions/runs/11070201829/job/30759445748#step:6:13

[Johennes]

Hm, looks like these are from links in the header:

<link rel="alternate" type="text/markdown" href="[/unstable/unstable/changelog/v1.5/checklist.md](view-source:file:///unstable/unstable/changelog/v1.5/checklist.md)">

Locally these look fine for me though:

<link rel="alternate" type="text/markdown" href="[//localhost:1313/changelog/v1.5/checklist.md](view-source:http://localhost:1313/changelog/v1.5/checklist.md)">

🤔

[Johennes]

I've opened #1954 to remove these links entirely.

[zecakeh]

It's not the only URLs that are affected, the one from the <meta http-equiv="refresh" …/> is too, and is more problematic. I believe that changing .Permalink to .RelPermalink in layout/shortcodes/changelog/changelogs.html fixes it though.

[zecakeh]

Basically, the problem seems to be the use of canonifyURLs: true with --baseURL. The former is deprecated so we should probably work on removing it (just removing it breaks some URLs right now).

[Johennes]

It's not the only URLs that are affected, the one from the <meta http-equiv="refresh" …/> is too, and is more problematic. I believe that changing .Permalink to .RelPermalink in layout/shortcodes/changelog/changelogs.html fixes it though.

Ah, I missed this. Thanks @zecakeh! Looks like .RelPermalink fixes this, indeed. I've opened #1956.