Time for decent changelogs (please!)?

[lukester1975]

There's been lots of changes recently which is nice, but not much documentation. Specifically, c5a5166 broke my tasks.json and it took a while to figure out why.

I'm sure nobody's got time or interest for writing documentation, but with e.g. conventional-commits and BREAKING CHANGE in the commit message an auto generated changelog would've been very helpful. Pretty much looks after itself once set up.

I kinda touched on starting this in #68 but alas no responses...

[eli-schwartz]

There are a variety of ways to produce changelogs that are significantly more conventional than something that literally names itself "conventional commits" but isn't remotely the conventional way to commit.

Meson itself uses one of them, so that could be copied probably.

[lukester1975]

Of course, hence "e.g."...

[tristan957]

I am interested in this. What more do we need to do?

[lukester1975]

Well I'm happy to add the hooks for conventional-commits as it'll only take 5 mins but it sounded like that wasn't an option!

[tristan957]

I think we are open to it if you can explain/provide resources on how it can help us!

[eli-schwartz]

The basic idea is that you change how you write commit messages so that you can use your commit messages as the changelog.

From memory this also means it becomes very difficult to include information that is relevant to git log but not relevant to a changelog; it also means you cannot edit your changelogs after the fact, whether to fix a typo or to include additional mitigation recommendations or anything else.

I highly encourage using the "snippets" approach to changelog management. Every PR should include at least one file in a changelog snippets directory containing the same text that conventional-commits would have said you should use for commit messages. The contents should be what you expect to go in the changelog. You can automatically group them using snippet filenames ending in ".bugfix" or ".feature" and edit them later on if you need to. Run a tool such as https://towncrier.readthedocs.io/en/latest/tutorial.html to aggregate them at release time.

[tristan957]

That sounds like a good idea.