Generate changelog both as RST and MarkDown

[felixfontein]

Result of ansible-community/antsibull-build#576 (with ansible-community/antsibull-changelog#139).

The resulting MarkDown file can be seen here: https://github.com/felixfontein/ansible-build-data/blob/markdown/9/CHANGELOG-v9.md

[webknjaz]

@felixfontein what's the motivation for storing both in a Git repo?

[felixfontein]

@webknjaz the RST for backwards compatibility, and MD because GitHub screwed up RST rendering so it doesn't work anymore for larger changelogs (which all Ansible changelogs are, and which quite a few collection changelogs also are), so users can still read them on GitHub in a nice way.

[felixfontein]

The ansible-core 2.15 changelog is also no longer rendered, for example: https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst The 2.16 changelog is still small enough. Whatever the limit is.

GitHub knows about this (see https://github.com/orgs/community/discussions/86715).

[webknjaz]

so users can still read them on GitHub in a nice way.

Ah, I see. I run pandoc in some of my CI/CD pipelines to do the conversion to GFM. That's not something that ends up in Git, though. Instead, it's what's attached to GitHub Releases that need Markdown too. Perhaps, it's something to consider doing with all those release automation efforts?

[felixfontein]

so users can still read them on GitHub in a nice way.

Ah, I see. I run pandoc in some of my CI/CD pipelines to do the conversion to GFM.

I tried using pandoc first, but it quickly breaks down for things like .. contents::.

That's not something that ends up in Git, though. Instead, it's what's attached to GitHub Releases that need Markdown too. Perhaps, it's something to consider doing with all those release automation efforts?

Adding a changelog excerpt to a GitHub release is a good idea as well; this should be rather easy to add on once that the MarkDown code is there. (For the ansible-core changelog this is already possible, antsibull-changelog generate --only-latest --output excerpt.md --output-format md writes the changelog excerpt for the latest version as MD into excerpt.md (this needs ansible-community/antsibull-changelog#139; without that PR you have to leave --output-format md away and get a RST file written).