Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Keep a Changelog

keepachangelog.com

Post reply on HN
Print view View original

21–30 of 53 posts

Re: Keep a Changelog

#21

Post by bsdubernerd »

mgkimsal wrote: post #5
bromuro wrote: post #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

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…

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.

Re: Keep a Changelog

#22

Post by majkinetor »

busbus wrote: post #15
petethepig wrote: post #9

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 fas…

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

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

Re: Keep a Changelog

#23

Post by majkinetor »

jayflux wrote: post #18

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 horr…

Gitlab has something like this since recently.

Re: Keep a Changelog

#24

Post by rezonant »

busbus wrote: post #15
petethepig wrote: post #9

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 fas…

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

Re: Keep a Changelog

#25

Post by rezonant »

jayflux wrote: post #18

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 horr…

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

Re: Keep a Changelog

#26

Post by busbus »

rezonant wrote: post #24
busbus wrote: post #15

Earlier quoted context omitted.

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 re…

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

Re: Keep a Changelog

#27

Post by rezonant »

jopsen wrote: post #12
bromuro wrote: post #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

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

Re: Keep a Changelog

#28

Post by fphilipe »

rezonant wrote: post #24
busbus wrote: post #15

Earlier quoted context omitted.

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 re…

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

Re: Keep a Changelog

#29

Post by rezonant »

busbus wrote: post #26
rezonant wrote: post #24

Earlier quoted context omitted.

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 re…

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 de…

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

Re: Keep a Changelog

#30

Post by limelight »

petethepig wrote: post #9

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 fas…

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

Post reply on HN