4 ms·

> 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.

> 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 https://www.conventionalcommits.org

nirvdrum 5y ago
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:").
jopsen 5y ago
I think I've often seen a feature land, followed by 2-3 small PRs fixing corner cases discovered during dev-release testing. Or you agree to land a PR with some aspects left to be fixed in follow up PRs. Typically, when projects are non-trivial in size, providing a changelog summarizing the important changes is useful.
- rezonant 5y ago
  Great point. So if you want that to come out atomically and "clean" you need to rebase the world- nontrival at best. I think that's worse than having multiple PRs around a feature. But I guess real engineers get it right the first time /s
mgkimsal 5y ago
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.
- bsdubernerd 5y ago
  Fully agree. There's a lot of value in providing a change summary which is _not_ tied to development history. Even as a dev, I usually don't care about your PRs. I'm pretty sure there will never be a 1:1 PR/feature history. Keeping the commit history in the repository clean must be useful for the developer (for example, to possibly revert atomically a change), not for the end user. Do you find more informative the Linus changelog between kernel releases listing a stack of PRs, or the nicer summary provided by kernelnewbies (and others) showing the prominent new features so you can drill down later? Git has very nice release notes. The language used in the release notes is completely different from commit history. It's a very nice gesture to write good release notes. It doesn't take long to do, and I find it beneficial for PRs that include notable changes that should get into the release notes also include a new line in there. It doesn't need to be perfect (surely it will change before being finalized), but it serves as a landmark for the final edit.

nirvdrum 5y ago

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:").

jopsen 5y ago

I think I've often seen a feature land, followed by 2-3 small PRs fixing corner cases discovered during dev-release testing. Or you agree to land a PR with some aspects left to be fixed in follow up PRs. Typically, when projects are non-trivial in size, providing a changelog summarizing the important changes is useful.

rezonant 5y ago
Great point. So if you want that to come out atomically and "clean" you need to rebase the world- nontrival at best. I think that's worse than having multiple PRs around a feature. But I guess real engineers get it right the first time /s

mgkimsal 5y ago

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.

bsdubernerd 5y ago
Fully agree. There's a lot of value in providing a change summary which is _not_ tied to development history. Even as a dev, I usually don't care about your PRs. I'm pretty sure there will never be a 1:1 PR/feature history. Keeping the commit history in the repository clean must be useful for the developer (for example, to possibly revert atomically a change), not for the end user. Do you find more informative the Linus changelog between kernel releases listing a stack of PRs, or the nicer summary provided by kernelnewbies (and others) showing the prominent new features so you can drill down later? Git has very nice release notes. The language used in the release notes is completely different from commit history. It's a very nice gesture to write good release notes. It doesn't take long to do, and I find it beneficial for PRs that include notable changes that should get into the release notes also include a new line in there. It doesn't need to be perfect (surely it will change before being finalized), but it serves as a landmark for the final edit.