Better ways to handle CHANGELOG.md

[tunetheweb]

The CHANGELOG.md file lists all the changes, and there is even a GitHub Action to ensure it's updated for each PR.

However this does create a merge conflict with nearly every PR (unless it's raised, and closed without any other changes happening in the meantime)

It also means (as noted in a Slack thread) you often have to raise a change with a blank entry (or let it fail), then add an entry - meaning extra commits.

As this project grows, this minor annoyance could grow more and more annoying, so is there a better way of doing this?

I've used the release-drafter GitHub Action on other projects. It basically creates a draft Release in GitHub and updates it every time a PR is merged. This draft PR is only visible to maintainers.

Here's an example for another repo I work on:

This also helps with release notes as can just convert that Draft to the next release. The Action will then automatically open a new draft on the next merge.

You could then copy that into the CHANGELOG.md file at release time? That would avoid the continual merge conflicts. The downside though is non-maintainers can't see what's upcoming, which is useful feature of the current process and maintaining these changes in CHANGELOG.md, which is visible to all.

The other alternative would be auto adding to CHANGELOG.md on merge to main? That might be a better way but would mean either updating main directly in a GitHub workflow (not really recommended!) or opening a Pull Request for each successfully merged PR - meaning we have two PRs for each one! So neither option is great to be honest.

Anyone any other thoughts on better ways to handle this?

[barrywhart]

@tunetheweb: The release-drafter GitHub Action sounds like a pretty interesting option. Can you explain how it updates the text of the draft release when a PR is merged? Does it get information from the pull request? Or does the person merging the PR have to manually provide that info?

[tunetheweb]

It just automatically enters the PR title, number (as a link) and username. No need for user to enter any info.

The person releasing can then tidy up the info as they please before releasing.

By default it will put everything in the one "What's changed" section, rather than the "Changed" and "Added" we currently use. But you can use labels on PRs to provide categories and then configure the release-drafter to use those. However currently non-maintainers cannot add labels so would need to figure that permission issue out first if wanting to use that (or the merger would need to add the label). Or alternatively just use the one category (I've often been confused whether my change should be in "Changed" or an "Added"), or have the releaser review and recategorise appropriately at release time.

Another option would be to use the auto-labeller so you could have any PRs with bigquery in either a file path, or mentioned in PR title (or body!) will automatically be given a bigquery label and so included in those release notes section. Not used this but think the label is then automatically added on merge (or there other GitHub Actions that can auto-label on PR open, which the release-drafter can then use).

And finally you can exclude pull requests (for example you wouldn't want the Release PRs included) by adding a special label.

It's quite funky, so lots of options!

[barrywhart]

It sounds like a great move. I'll see if I can get others to weigh in as well -- I wouldn't want to make a process change like this without buy-in.

[pwildenhain]

I'm bought in, this sounds amazing -- really cheap and easy, but still quality, documentation

[tunetheweb]

Automating it would also hopefully avoid issues like this first entry where someone entered a bad link markup (space between the [#] and (https...)) and also didn't update the issue number:

[dmateusp]

I haven't been active for a long time but this has a big 👍 from me

We use auto labeler at Earnest but I think we would need to clean up the labels here and the rules could be a little tricky. Maybe we could try it manually for a while and then see if we can really automate it without adding too much complexity?

[alanmcruickshank]

YES YES YES YES YES. I love this idea. Big thumbs up from me 👍 .

I don't know if we need to go big on labelling for now - perhaps just bugs vs not bugs might be most appropriate given the number of changes.

[tunetheweb]

And it's live! Check out https://github.com/sqlfluff/sqlfluff/releases

Screenshot below (note only non-maintainers see Draft releases so @barrywhart took this screenshot for me):

Maintainers, feel free to add bug or enhancement labels to PRs before merging, and they'll be put into that cateogry. Otherwise they just fallback to the generic "What's changed" category as per above examples. Note non-maintainers can't add labels (it's a long standing issue apparently).