The release notes are frequently edited by many different authors whose default is going to be Markdown syntax. It’s important that we make adding release notes as low friction as possible,
and I think requiring them to learn Restructured Text (RST) syntax is a waste of their time.
Whether RST+Sphinx or Markdown+Sphinx is better at achieving every possible formatting goal is not relevant here. It’s purely about making the common things easy to do correctly.
Some pros:
Markdown is the default syntax for GitHub, Reddit, Discord, Discourse (aka this very forum) and many others.
Fewer mistakes because people are trying to use Markdown syntax in RST.
It makes the common path easy. Adding a bullet point, single sentence, with a link.
Markdown can more easily be rendered locally in an editor.
Release automation can pull GitHub comments into the release notes without filtering the syntax.
Some cons:
We still have to use Sphinx directives for the fiddly bits, switching to Markdown doesn’t change that. However, 99% of people won’t be editing those in the release notes.
GitHub does have support for rendering RST as well, though I wonder how many people realise that.
Plain Markdown has some big limitations, for example table cells can only be a single line. However, I don’t see the need for that in release notes (and there is an escape hatch where you can write RST inside a MyST directive if you really needed it).
We will have a mix of formats in the documentation, but we already have some Markdown documents they are just less prominent than the release notes.
For reference, in the whole monorepo we have 2037 RST documents and 258 Markdown documents. In the LLVM docs specifically, there are 1183 RST documents and 14 Markdown documents.
One other subproject, MLIR, uses Markdown for their release notes (though I don’t know the justifications for that choice).
I think this a welcomed change, markdown is much more recognizable for most developers.
But I also think we need to think about how to approach the release notes more generally. So sorry for hijacking your thread to think out loud. Currently they are often not collected and when we branch to the release branch it can create very annoying merge problems.
Another approach many other projects are using is that the release notes are generated from the git commit messages. You can use special tags to highlight what should be included and how it should be tagged. This will most likely lead to more complete release notes, but maybe less nicely edited? Unsure. We could also use github ci integrations to check for release notes and show how they would be rendered directly in each PR. It completely avoids the problems with merge issues and manually needing to update files. It would also be easier to link to each PR / commit this way to include that in the release notes (something that needs to be done manually now). Something like git-cliff could be used.
I think maybe a combination of the two approaches could be useful for us. Generate a first draft from the commit messages, then the release manager would open a PR with the generated notes towards each project for the release branch and we could edit and commit them from there.
I think that taking release notes from git commit messages is not ideal, because those are immutable. You can’t go back after the fact and improve the wording of a message, or add one if you forgot it initially.
My ideal workflow here would be to allow including release notes in the pull request description. Have some kind of specific syntax so tooling can then collect release notes from all the merged PRs for the release and assemble a first draft of the release notes.
In any case, independently of any larger improvements, I do think that converting the release notes to markdown is a good idea in any case.
Release notes derived from git commits seems bad. The person in the loop deciding what to communicate to users is a hassle for those authors but a huge multiplier considering how many users are out there. The audiences are also completely different - git commit is largely breadcrumbs to give developers a chance of working out what has gone wrong later, release notes are roughly marketing copy.
Markdown is a good call though. I still don’t know rst so it’s likely I never will - I edit the docs by cargo culting surrounding syntax and some iteration, and try to avoid editing them at all because it takes ages and is very frustrating (since I haven’t learned rst…). Markdow is rather tolerant of people guessing the syntax from context as well as more likely to have been encountered elsewhere on GitHub beforehand.
Adding to the negative stance toward generating release notes from commit history, reverts and re-lands are going to worsen the quality of such release notes if not handled properly, which doesn’t sound a trivial problem to me.
