Post-1.0 thoughts: CHANGELOG.md

[jcollie]

OK, so I know this is a little early, but I'd like to propose that after 1.0 is released any PR should include a patch to CHANGELOG.md that summarizes the changes being made. Maybe not every PR, but at least ones that have user-visible changes like new/removed config settings, config settings that have changed meanings, etc.

[stepanbujnak]

I like this idea, but is there a way to enforce that other than PR reviews?

[jcollie]

I suppose in theory you could have a git hook or a CI workflow to check it but I think that it would be better to just have it enforced manually by reviewers, at least for now.

[JakeWharton]

If you create a .github/pull_request_template.md file, you can pre-fill the PR description section with an area that has a checkbox to aid in bringing attention to this requirement.

For example, I use:

  
  
---

Please confirm:

- [ ] `CHANGELOG.md`'s "Unreleased" section has been updated, if applicable.

Which renders like:

Secondary commit paragraphs would go here automatically, or the user's manually-written description.

---

Please confirm:

• CHANGELOG.md's "Unreleased" section has been updated, if applicable.

[mitchellh]

I don't like PRs all updating a shared changelog file because based on past experience it leads to a lot of conflicts.

I'd love to automate changelog creation. My main requirement here is that changelog entries are still hand-written. I don't think that auto-generated changelog entries based on commit messages, PR titles, etc. work well. I've at least never seen that work well.

In my prior life we created and used go-changelog. That works really well, and I'm not against bringing it back in here except it's not super well adopted outside of HC. We wrote that because nothing that satisfied the above requirements really existed but maybe its been long enough that something exists?

[auscompgeek]

I don't like PRs all updating a shared changelog file because based on past experience it leads to a lot of conflicts.

I concur. From past experience having a directory of changelog/news fragments (e.g. a changelog.d directory) works significantly better when you want to avoid generating changelogs from commit messages. I see go-changelog is another implementation of that idea.

towncrier is probably the most popular implementation of this idea in the Python ecosystem I've come across, though a quick web search finds scriv too.

[Integralist]

Yeah we've had issues with changelog generation. We settled on using CI to enforce commit messages were of a specific format so that we could at least have consistency in the changelog we auto generate (we also had to roll our own as nothing in the open-source community met our needs). It's not perfect but that approach worked for us.

[jcollie]

towncrier look interesting, but maybe a little complicated. I like that you mainly just stick a text file in a certain directory.

[herberttn]

@mitchellh I think changesets could be what you want here

[reitzig]

I can recommend miniscruff/changie. A neat, easy to use CLI tool with all state stored in plain files that are easy to handle yourself if need be.

I've implemented a workflow step that forces each PR adds to add at least one entry, too; they had easy to follow documentation on how to achieve that.

[yorickpeterse]

At GitLab we used a bunch of different techniques over the years. The one we eventually settled on was using Git trailers to flag commits as "include in the changelog", with the subject line becoming the entry. While GitLab's approach requires a GitLab specific API, I ended up writing a standalone tool that essentially does the same thing, such that I could use it for my own projects. Here's an example commit, and here's what the resulting output looks like.

The requirement of this approach is that developers at the very least write a decent subject line, and of course add the changelog trailer. This means people can't just submit a PR with 10 random commits with messages such as "one more attempt" or "now it works", unless a maintainer is willing to squash them together and rewrite the commit message. For GitLab this did require some extra effort early on, though looking back I think it wasn't necessarily any more difficult compared to adopting a different technique.

[JakeWharton]

This is similar to what we settled on for use in Android's unbundled libraries (i.e., those not shipped as part of the OS itself).

One thing we did differently, though, was not explicitly use details from the commit automatically. This is because we determined the commit audience were developers/maintainers of the library, whereas the change log entry was targeted towards users of the library. While often the summary and change log entry were similar, they were not always the same.

Here's a random example: https://android.googlesource.com/platform/frameworks/support/+/b3e9aa48cd0749f588b121518d9bd1853886dada%5E!/

I suspect with development of an application the disparity between the note users see in a change log and that which the maintainers see (in PR titles and git log and such) is even wider.