Keep a Changelog
keepachangelog.com
Keep a Changelog
1–10 of 53 posts
Re: Keep a Changelog
#2> 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.
I’d rather fix that. I’ve been following the suggestion from this website in the past. It is a nice take but tedious and boring.
Better have commit messages. For example: https://www.conventionalcommits.org
Re: Keep a Changelog
#3[deleted]
Re: Keep a Changelog
#4Past related threads:
Keep a Changelog - https://news.ycombinator.com/item?id=22295555 - Feb 2020 (1 comment)
Keep a Changelog - https://news.ycombinator.com/item?id=17631326 - July 2018 (71 comments)
Keep a Changelog - https://news.ycombinator.com/item?id=12370119 - Aug 2016 (45 comments)
Keep a Changelog - https://news.ycombinator.com/item?id=9054627 - Feb 2015 (43 comments)
Re: Keep a Changelog
#5> 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. I’d rather fix that. I’ve been following the suggestion from this website in the past. It is a nice take but tedious and boring. Better have commit messages. For example: https://www.conventionalcommits.org
It's still not great - you're still primarily talking about changes made to the code, not the net effect change for users. Sometimes that messaging can overlap and serve both audiences (people who want to know code changes vs people who want to know functionality changes), but IME it's less common than conventional-commit advocates seem to think.
Using commit logs as part of a changelog, or as the starting point for additions... sure.
Re: Keep a Changelog
#6Or you could just filter the commit history and use squash instead of merge.
Re: Keep a Changelog
#7Or you could just filter the commit history and use squash instead of merge.
I still think a changelog may be useful. For example, if you are writing a library, a changelog should include a section for breaking changes. Ideally you should also be providing a migration guide, but a list of breaking changes should be done at a minimum.
Git history is also not ideal for giving to users since the history is primarily intended for developers. If you actually want to use git history for this, I actually think non-squash merges are better since you can have the merge commit be very high level and use the other commits for technical details and incremental changes. However, even if you do regular merges, you absolutely still need to keep your history clean via rebasing before sending out a PR.
Another tip for keeping your PRs clean without confusing people is to create a separate branch while working on feedback from the PR so you can still manipulate the history as needed while backing up your code to the remote server.
Re: Keep a Changelog
#8> 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. I’d rather fix that. I’ve been following the suggestion from this website in the past. It is a nice take but tedious and boring. Better have commit messages. For example: https://www.conventionalcommits.org
I come across way too many commit messages that exist solely to drive some sort of connected tool (CI, CD, issue tracker, etc.) or have some arbitrary character cut-off, so the messages are borderline cryptic. Add the typical back-and-forth on design in repos and you end up with entries that don't correspond to what's shipped in the release. The reverse chronological order of messages doesn't help much either. And a surprisingly large number of projects don't tag their releases, so picking where to start reading from is an exercise in frustration.
I find a changelog is a great place to provide a high level summary of changes and a good opportunity to highlight backwards-incompatible changes or API changes users should be aware of. If your commit messages are of the form "Fix #123" (without the issue title), it's also a good place to summarize #123 so your users don't have to cross-check everything with GitHub.
I'd love to see a commit log that was consumer-friendly. But, as long as devs are writing messages within the constraints of other tools, I don't see it happening. Conventional commits is an interesting idea, but for those keeping messages to 72 characters, it eats up a fair bit of the message. Also, a lot of it ends up being noise that you wouldn't want in a user-facing changelog (e.g., "test:" and "refactor:").
Re: Keep a Changelog
#9Semantic pull requests [0] + conventional-changelog [1] + squashing PRs and you get almost the same results (and more) with great automation and self-documentation for the whole process:
* you'll never forget to add something to changelog
* you get links to PRs in your changelog
* it's much faster to make edits to PR messages compared to editing files
* outside contributors get familiarized with the practice much faster (imagine getting new contributors to update changelogs)
We recently adopted this practice at Pyroscope and it's been working out pretty well for us [2], I can certainly recommend it.
[0] - https://github.com/apps/semantic-pull-requests
[1] - https://github.com/conventional-changelog/conventional-chang...
[2] - https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELO...
Re: Keep a Changelog
#10See also: The deb-changelog format[0].
[0] https://manpages.debian.org/testing/dpkg-dev/deb-changelog.5...