Hacker News Reader

Comment by fphilipe | Hacker News Reader

I am definitely more in the changelog-as-a-file camp. From https://keepachangelog.com/:

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

View on HN

> they're full of noise. Things like merge commits

From another angle, merge commits can also be a solution to the problem. `git merge --no-ff --edit` can be a great way to summarize an entire branch of commits. Most PR tools will give you an easy way to create those kind of merge commits. Don't settle for the default "merge branch x into y", create a meaningful title and fill in details/summary of what happened in the branch. With traversal tools like git log --first-parent you can see a high level of just your merge commits with the gnarly details of whatever steps led up to the merge commit itself.

I've certainly seen good projects where `git log --first-parent` was always a useful first pass changelog (no matter how "clean" the rest of commits were or were not). Probably still not a changelog you should send as a document to end users (because still written from a development standpoint rather than a user standpoint), but a good place to start writing the end user documentation.

Me too, but some tools combine the best of both worlds. In my team we use commitizen [1] which drinks both from keepachangelog and conventional commits and we are quite pleased with our changelogs so far.

[1] https://commitizen-tools.github.io/commitizen/#features

Noise can be excluded.

spent 3 years on a team hoping they would step up a write meaningful changeset titles...

however. ended up just getting:

- fixed things. - creates new feature x - fixed broken thing.

instead of something that's appreciable by non technical people:

- when navigating to the nuclear launch code dashboard, a user is no longer mocked for having a likeness to <current unpopular person>.

point here is. if your team didn't write good squash merged PR titles before, they won't magically start doing so because you're using changesets.

Reply on news.ycombinator.com