Keep a Changelog | Hacker News Reader

Keep a Changelog

keepachangelog.com

223 pointssoheilpro51 comments

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

I'm having trouble figuring out what a "semantic pull request" is from that link, it's not a concept I've heard of before, and I'm interested. I mean, i assume it's some conventions for what goes in PR message, but what are they? Is there a better link?

In general, as a developer-consumer of them, I have found automatically-generated-from-commits changelogs to be not so useful, but I don't know if I've experienced any using the conventions you are recommending (which I dont' understand!).

In the small projects I write, I include links to the PR in the manually created CHANGELOG (the delta of which is part of the PR) simply by making the PR, then making another commit/ammend in the PR to add it's own url to the CHANGELOG. These are some extra steps, it's true.

You use the title of the PR as a changelog item instead of every commit message.

It forces you to think a moment for a good PR title, but it is an small price to pay when it gives you a 0 extra work changelog that is good enough for semi-internal use.

Instead of using the title, could the changes be put in the description using a custom syntax? Prefix the line with `CHANGELOG:` or something like that.

    git --no-pager log | grep 'CHANGELOG: '

https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Gi...

I really dislike this because, while it's easier for the author, either the changelog or the commit messages become less useful. In fact, I might just copy the last time I ranted about this [1]:

> Ugh. One of my pet peeves is the generation of release notes from commit messages. Commit messages and PR descriptions have a different audience (i.e. contributors) from release notes (i.e. users).

> For example, take a look at ESLint's autogenerated changelog [1]:

    67c0074 Update: Suggest missing rule in flat config (fixes #14027) (#15074) (Nicholas C. Zakas)
    cf34e5c Update: space-before-blocks ignore after switch colons (fixes #15082) (#15093) (Milos Djermanovic)
    c9efb5f Fix: preserve formatting when rules are removed from disable directives (#15081) (Milos Djermanovic)
    14a4739 Update: no-new-func rule catching eval case of MemberExpression (#14860) (Mojtaba Samimi)
    7f2346b Docs: Update release blog post template (#15094) (Nicholas C. Zakas)
    fabdf8a Chore: Remove target.all from Makefile.js (#15088) (Hirotaka Tagawa / wafuwafu13)
    e3cd141 Sponsors: Sync README with website (ESLint Jenkins)
    05d7140 Chore: document target global in Makefile.js (#15084) (Hirotaka Tagawa / wafuwafu13)
    0a1a850 Update: include ruleId in error logs (fixes #15037) (#15053) (Ari Perkkiö)
    47be800 Chore: test Property > .key with { a = 1 } pattern (fixes #14799) (#15072) (Milos Djermanovic)
    a744dfa Docs: Update CLA info (#15058) (Brian Warner)
    9fb0f70 Chore: fix bug report template (#15061) (Milos Djermanovic)
    f87e199 Chore: Cleanup issue templates (#15039) (Nicholas C. Zakas)

> I'm reading release notes to get a feel for how the new release might impact me. This takes so much time to scan, because there's so much useless cruft (to me, as a user) I have to ignore.

> What's worked very well for me is to simply have an "I updated the changelog, if applicable" entry in my PR template checklist. Then when I cut a new release, I simply add the release date above the release notes currently listed under "Unreleased", and they'll list all relevant changes, reviewed during the pull request to verify that it is relevant to users.

> [1] https://github.com/eslint/eslint/blob/master/CHANGELOG.md

[2] https://news.ycombinator.com/item?id=28757317

It always depends on your users. Such a changelog is suitable for stuff other developers use, but not for end users.

But it is a _way_ better starting point to write a changelog that 'usual' commit messages or PR descriptions.

I disagree. I publish to the end users and they are grateful all the time.

I use custom scheme tho, using Gitlab issue title and issue labels. I find this more meaningful since one issue can contain multiple PRs and I still want single changelog line.

How can I, as a user, know if bug x, or issue y is resolved, without a changelog?!

Nobody suggested not having a changelog.

Seconded, I've seen semantic PR plus squash add a lot of value both for the engineering side and the product side.

We do this and it works great, but I've still found value in summarizing things in a digest (ie changelog or release notes, depending on the context)

Thirded? Tertiaried? This is something I always beat myself up for not doing consistently. Automating it at a minimum checks the box, and also can provide real value.

May I ask you why you want to squash every branch ?

What is the size of the resulting commit (in terms of average modified files, lines of code) ?

I've shared this anecdote elsewhere but it's my go-to example. We recently had a new engineer join our team, we gave them a small piece of work related to a bigger feature we had completed months before they arrived. They tracked the feature back to the squashed PR commit, which of course referenced the Github PR URL- in there they had the engineer's summary and implementation caveats, the review comments from the rest of the team and the discussion context. They could reference all the commits made throughout the process from there. The PR itself used "Closes #X" syntax, so they could jump back to the engineering task and up into the product backlog item that spawned it. They nailed the change the first time :-)

> What is the size of the resulting commit (in terms of average modified files, lines of code) ?

Lately I'm starting to advocate squashing PR branches even if they have only a single commit. The real benefit here is that Github puts the PR URL into the squashed commit message. It automates the "context links" regardless of whether a PR branch ends up being 1 commit or 50

I understand the needs. But to me, I can’t see any real value to squashing other than cleaning local history before sharing the code. Also, and that’s important for me (maybe other people doesn’t care of it) I lose the ability to bisect more precisely. When I know that my guilty commit is a squashed one, I have to watch every modification to understand what went wrong, which takes time for me.

Also, everything you describe can be achieved with a merge commit. As a side effect, when you look at the history, you may be annoyed with small commits that may not interest you. But Git can help by displaying only merge commit (with --first-parent option).

Ah bisect is a great use case here.

True that you can achieve it in a merge commit. And I think Github includes the PR URL in a merge commit as well iirc. I suppose my main argument is really just that the always-rebase strategy that was trendy for awhile has some downsides over squash/merge commit /shrug

I don't think I understand what "squashing PR branches" means (a github feature I haven't noticed?), but:

> The real benefit here is that Github puts the PR URL into the squashed commit message.

While not in the commit message, github will show you the PR a commit is part of in it's commit view regardless, also for every commit in a PR whether it's one commit or 50. Which I do find invaluable for tracing the documentation of a change, agreed! Not everyone knows about this feature (I don't think it's been there forever) in github UI.

Eg notice the `#279` included in this github commit UI display (the PR was, I'm pretty sure, not "squashed").

https://github.com/traject/traject/commit/10339e774e92e57f44...

The merge commit also includes the link to the PR when merged via the GitHub UI (or locally via `hub merge $PR_URL`).

One typical reason would be easier history following and eventually revert.

Yep, I love this workflow.

We use release-please to automatically generate WIP "release PRs" so we can see the exact changelog (for a candidate release) drafted as merges come in.

[0] https://github.com/googleapis/release-please

Semantic pull requests work well for a slow pace of work, and I use them all the time.

I also recognize that for full-speed delivery, they are suboptimal in that they sit directly on the critical path. After reviewing the code of the PR, there is now an extra context switch to also review the title/semantics.

So the complexity of turning a list of PRs into a changelog does not disapper, it gets hidden within each individual PR.

Past 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)

I've been hand-writing a CHANGELOG.md file, in each of my repos, for a long time. Before that, I used to keep it as a section of my README.md file.

I got used to the second file, after using CocoaPods. I don't really use CocoaPods anymore, but they would render the CHANGELOG.md file in a separate tab, which was nice. I don't think anyone else does that.

I think a hand-written changelog is better than a semantically-generated one, because it connects the developers' mindset to the consumer (usually, another developer). It says "These are the aspects of this release that I think are important."

A semantically-written changelog doesn't actually need to be kept. It can be auto-generated on demand. As long as the developer keeps good commit notes, with things like issue numbers, then this could be useful.

FYI. Here’s a very long CHANGELOG (over ten years):

https://github.com/bmlt-enabled/bmlt-root-server/blob/master...

It was in the README for most of that time. It has just been broken out into a separate file, by the new team.

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

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.

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

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.

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

GitHub have developed a feature to generate release notes based off the commit history, might be worth trying. You can configure it to filter out users, group by labels etc https://docs.github.com/en/repositories/releasing-projects-o...

For those saying “just use commit history”, I once had to sift through 200 commits because the library author was too lazy to separate the breaking changes from the patches. It’s horrible for users of your library, a changelog doesn’t have to replicate your commit log but it should at the least be the “highlights” or need-to-know version of it.

> For those saying “just use commit history”, I once had to sift through 200 commits

Exactly... I think it's a good idea to "roll up" the impact of the changes so that users and external developers can easily understand what was changed without getting too "in the weeds"- raw commit messages are generally the opposite of that.

> GitHub have developed a feature to generate release notes

The annoying part here is that if you are using a branch-based CI auto-deployment (without an "Approve" step) then you have to push the branch before writing the release notes. Anyway I just do `git cherry -v release` or so from `main` (for instance) and paste the results into the Release Notes at the bottom and put my summaries at the top. The benefit of just pasting the results is that Github will detect the commit IDs and link to them automatically. It makes for a pretty good experience where you can sum it up and have the full commit messages for those interested.

Gitlab has something like this since recently.

The approach I like to take is to curate issues and PR with semantic titles and organize them by label ("bug", "enhancement", etc) or linking PRs to an already curated issue. This way automation can use these to generate the changlog for me on each release based on closed issues and unlinked PRs since the last release.

We wrote Chronicle to do that automation for us: https://github.com/anchore/chronicle .

The nice thing about this... since you typically curate issues during the development process anyway, if you're doing that right then you get a nice looking changlog for free! We use this approach with our core tools, Syft and Grype (some changlog examples: https://github.com/anchore/syft/releases/tag/v0.31.0 and https://github.com/anchore/grype/releases/tag/v0.26.1 ).

Always happy to hear new feature ideas and possible customizations for Chronicle (put in an issue and let's chat )!