Start keeping a changelog

[fungjj92]

Previously we deployed to production straight from develop. Since recently aligning our deploy workflow with the usual (master --> jenkins --> prod; develop --> jenkins --> staging), we'll want to keep a Changelog. Begin after version 1.0.0

[sharph]

I feel that generated changelogs (changelogs from git messages) are not good changelogs.

See http://keepachangelog.com/en/1.0.0/

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

[CloudNiner]

I generally agree. For the API we're using https://github.com/skywinder/github-changelog-generator which generates changelogs that look like:

https://github.com/azavea/climate-change-api/blob/1.2.1/CHANGELOG.md

These seem ok, and hit most of your comments, in that they summarize PRs which are generally distinct units of change, rather than individual commits. I completely agree that individual commits are generally useless.

I believe the original proposal here was to use the same tool for this project.

I personally think that a handwritten changelog in the style of keepachangelog is best, with different sections for bugfixes/additions/breaking changes/etc. Those can be hard and time consuming to write and have the potential to miss changes. This is a smaller project, I don't feel strongly whether we continue to use github-changelog-generator, or roll our own. Long term I'd like to see our team generally settle on one or the other, knowing the tradeoffs of each.

[rmartz]

I tend to like the idea of using PR names to populate a changelog dynamically, since 95% of the time there's a 1:1 correspondence between PRs and things changed, and for the remaining 5% of the time it's possible there should be. It also helps avoid the chore nature of adding a changelog entry that says roughly the same thing as the PR, as well as prevents merge conflicts for active projects.

Only problems I see are twofold:

• Project participants would need to be aware that the PR name is significant, because changelog entries that are essentially just prettified branch names aren't very helpful
• For major shifts it's impossible to provide extended context within the changelog, and signifying substantial or notable changes may require the use of emojis.

...on second though I'm totally down with this. Emoji PR titles! 🎉