Automate inclusion of release notes into Plone 6 documentation

[stevepiercy]

I just noticed that we do not have Plone release notes in Plone 6 Documentation. I also do not know whether we have them compiled in a single file anywhere.

We have Volto release notes automatically included. Let's do the same for Plone. Here's what Volto does: https://github.com/search?q=repo%3Aplone%2Fvolto%20copyreleasenotestodocs&type=code

• Proposed destination: root of Plone 6 Documentation, entitled "Release Notes", appearing under the "APPENDICES" heading.

What are the bits and pieces that need to be identified and put together?

[mauritsvanrees]

For Volto it could be improved. It looks like this simply gets the CHANGES.md from the main branch. This means all Volto 18 alpha release are there, which is fine, but for Volto 17 the latest is 17.4.0 from November, and for Volto 16 the latest is 16.21.1 from June.

Perhaps the CHANGES.md from the 16.x.x branch should be copied, since that is the default to go with Plone 6.0. Or from the 17.x.x branch since that is the latest final version.

But at least there is something, which cannot be said for the backend/Classic UI.

[mauritsvanrees]

The release notes are hand compiled by me in the coredev buildout repo. For Plone 6.0 this is done on the release/6.0-dev branch. When it is finished, I make a tag of it. For 6.1 it is the release/6.1-dev branch.

Latest release notes are then here, for 6.0.10.1. And here is the full changelog (or as full as we can reasonably get it).

The changelog is automatically generated using plone.releaser by the bin/changelog command that you can run in the coredev buildout. For 6.0.8 the command would be:

$ bin/manage changelog --start=6.0.7 --end=6.0.8 > release/changelog.txt

Afterwards, I do a small bit of cleanup, because some warnings are printed.

I call it changelog.txt, but really it is ReStructuredText. The command looks for CHANGES.rst and CHANGES.md for all packages for which the source is defined in sources.cfg and tries to get the parts relevant for this Plone release. Several packages have their changes in MarkDown now, so we have a combination of RST and MD, which may make this tricky to properly get into the docs if we want. But we may want to restrict it to the release notes.

One possible way of including this in the docs, would be to create a backend/release-notes directory. Then for each tag of buildout.coredev, copy releases/RELEASE-NOTES.md to a new directory. Or keep them all in one directory, and call it <tagname>.md.

Instead of copying it from git tags, we could copy it from dist.plone.org/release, where every release has its own directory. The contents should be the same.

I am happy to adjust the MarkDown of future release notes if needed, as long as I can copy them to community.plone.org as announcement.

And yes: having these in the docs would be nice!

[stevepiercy]

For Volto it could be improved. It looks like this simply gets the CHANGES.md from the main branch. This means all Volto 18 alpha release are there, which is fine, but for Volto 17 the latest is 17.4.0 from November, and for Volto 16 the latest is 16.21.1 from June.

I am not sure what you look at? We capture all minor and bugfix releases for Volto.

This: https://github.com/plone/volto/blob/main/packages/volto/CHANGELOG.md#1740-2023-11-04

Renders as this: https://6.docs.plone.org/volto/release-notes/index.html#id52

[stevepiercy]

MyST can parse both .rst and .md files.

There is a utility that can convert markup from reStructuredText to MyST that we used for all the repos that are included in the Plone 6 Documentation, plus a few that have already been converted from Plone 5.2 Documentation just waiting for someone to review them for accuracy and get ported to Plone 6.0 Documentation. See Importing external docs and converting to MyST. It's pretty good, and requires minimal cleanup, depending on the quality of the original reStructuredText, of course. I am happy to do one-time conversions and clean-ups, if that is a barrier.

[mauritsvanrees]

I am not sure what you look at? We capture all minor and bugfix releases for Volto.

This: https://github.com/plone/volto/blob/main/packages/volto/CHANGELOG.md#1740-2023-11-04

Renders as this: https://6.docs.plone.org/volto/release-notes/index.html#id52

That is Volto 17.4.0. Latest is 17.15.4: https://github.com/plone/volto/blob/17.x.x/CHANGELOG.md

And latest from Volto 16 should not be 16.21.1, but 16.31.3: https://github.com/plone/volto/blob/16.x.x/CHANGELOG.md

Maybe the Volto release notes in the docs should have one directory or file for Volto 18, one for 17, one for 16. But the earlier parts of the Volto 17 notes would be there twice, and the earlier Volto 16 notes even three times.

[stevepiercy]

Oh, yikes, you're right. That's misleading, as if Volto 17.4.0 was the latest release of that branch.

Let's ask @sneridagh to think about this, as it would affect his workflow, and he might have a trick or two up his sleeve.