4 ms·

I'm not a big fan of auto generated commit logs - they just have too much noise in. You might as well look at the git history. Changelogs should be for users to

by nickcw 2y ago

I'm not a big fan of auto generated commit logs - they just have too much noise in. You might as well look at the git history. Changelogs should be for users to read. I have a program which generates the first draft of the rclone changelog from the first line of each git commit. I try to encourage all contributors to make the first line of their commit message be something a user would like to read in the changelog. Instead of `fixed nil pointer error` have `fixed crash when copying file to xyz backend`. https://rclone.org/changelog/ https://rclone.org/changelog/ I also spend maybe an hour each release editing the auto generated changelog, removing the noise (refactored X, fixed docs for Y, made tests for Z work), condensing multiple entries, reorganizing, moving things to the correct section, linking stuff etc. Where the committer didn't write a sensible first line commit message I go back look at the diff and rewrite it. I try to put the important things first in the changelog and keep it brief. The changelog is a heads-up for users that things have changed or been fixed and users don't want to spend hours reading it. I think for an open source project like rclone where I review commits from all different levels of developer, and from all different levels of English mastery I'd have too much difficulty getting every commit message written in https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ style to use a tool like git-cliff to generate the changelog without editing it. Would I like not to spend an hour or more of my time editing the changelog for each release - most definitely! However I owe it to the users to make something nice and I don't think I can delegate that to a program.

lloydatkinson 2y ago
Did you look at the example changelogs git-cliff creates? > I try to put the important things first in the changelog and keep it brief. The changelog is a heads-up for users that things have changed or been fixed and users don't want to spend hours reading it. Provided the commits use conventional commit format such as "feat(thing): fixed crash when copying file to xyz backend" or "fix(database): generate migrations correctly" not only do you get the type of commit but also the category or area. git-cliff and others then use that to automatically add sections for each category of commit. This wouls surely needing to spend hours on writing changelogs, which seems an insane amount of time to me. > I also spend maybe an hour each release editing the auto generated changelog, removing the noise (refactored X, fixed docs for Y, made tests for Z work), condensing multiple entries, reorganizing, moving things to the correct section, linking stuff etc.
- martypitt 2y ago
  > Did you look at the example changelogs git-cliff creates? This isn't easily discoverable from the landing page -- I think the site could benefit from an "examples" sections. Given the focus on customizability, it'd be good to get a sense of what's possible, rather than diving straight into Get Started, before I've decided that I want to use the tool.
- mathstuf 2y ago
  I find that conventional commit wastes space in the summary for little gain. Categories are subjective and just not worth discussing much of the time. Even with it, how do you deal with things like reverts to commits that shouldn't be mentioned in the changelog anymore? Updating text or copy is also annoying. I've found that storing changelog snippets in the repository is far more scalable (one file per note in a directory). This allows future changes to update changelog entries and reverts to just remove them completely. There's also enough trouble getting Github and GitLab to support commenting on commit messages (something they should do anyways!) that feedback on release notes stuffed into commit messages is then a third-class process. They can still be collated and gathered just like from the commit messages, but they're actually tracked by git and there's no confusion when backporting changes: the release note comes with it without having to merge with conflict notes, `cherry-pick -x` notes, etc. You're also not limited to a measly single line for describing your change.
  - teeray 2y ago
    > I find that conventional commit wastes space in the summary for little gain The things that conventional commits adds to commits were intended to be accomplished by commit trailers (Co-authored-by, Signed-off-by, etc.). Nobody is stopping anyone from having a “Change-type” trailer and a “Product-area” one too. You can have these in a template on your machine so it’s the same amount of typing involved. You can even tack on `--trailer` to `git commit` if you insist on using `-m` for everything and never filling out the commit body (commits devoid of detail are another plague on repositories).
    - keybored 2y ago
whoomp12342 2y ago
if you start your work under a branch to match a card issued by product (through your sprint/kanban ticket system), then rebase all your commits into that branch, which is what becomes part of that then it CAN be user digestable.
madeofpalk 2y ago
Automated changelog generation tools usually have a mechanism to allow you to opt commits in or out of the changelog. So you still get authorial control over the changelog, but when it comes to actually creating the document it’s automated because you wrote the individual lines when you wrote the code. It’s basically the same as what you’re doing, but in a different order.
- remram 2y ago
  That works if commits can be looked at in isolation to build the changelog. What if a commit introduces a feature, and a subsequent one changes it? Is there a syntax for your commit to replace an earlier changelog entry? Cue the Kubernetes release notes, which contain 20 separate "update to Go x.y.z" for each release.
  - madeofpalk 2y ago
    The way I've always done it is that it's controlled via labels on PRs. If you want to remove a PR (and by swashing merges). If you want to remove a PR from the changelog, remove the label.
stusmall 2y ago
I've been recently working on the process to improve this at my day job. A coworker made a point to make very clear distinction between change logs and release notes, and its made a huge difference in how I approach and think about the problem. A changelog is a raw, engineering driven manifest of everything that has changed. This log sometimes needs more context. Okay the wizbang had a hoozit added, what the hell does this mean and why do I care? Or it needs less and a lot of the engineer rambling needs to be stripped out. The changelog is an input to a release notes process. This is where refine the wording and fix it up for end user consumption. Having a clear changelog pointing back to individual PRs and engineers lets us go back and talk to folks and clean things up and have final wording checked. There is no amount of automation that can every replace this process. It's part of the finishing touches and craftsmanship our customers expect. Nothing I'm saying here is any different than what you are saying. My changelogs are the same as your drafts. I just found having those clear definitions and separate terms made it easier to sell the process and have people understand the big picture.
- OJFord 2y ago
  > A changelog is a raw, engineering driven manifest of everything that has changed. This log sometimes needs more context. Okay the wizbang had a hoozit added, what the hell does this mean and why do I care? Or it needs less and a lot of the engineer rambling needs to be stripped out. With that definition it literally is just the git log though isn't it, which was GP's point? I know you're writing in agreement, but it sounds like your changelog is an intermediary step, and I don't understand why it's needed? To fill in the gaps from lazy commit messages?
  - gregmac 2y ago
    > With that definition it literally is just the git log though isn't it I think you're right if you go by that definition ("changelog is a raw, engineering driven manifest of everything that has changed"), but there I think there is an intermediate step between git log and the user-facing release notes, whether or not it's formalized, which is to basically squash the messages into the list of effective changes since another point-in-time (eg: last release). Let's say you add a feature, then refactor it a bit, then fix a bug in that new code. The only thing that needs to be there is the "Added a feature" part, because the rest is meaningless noise when you compare it to the prior release. Likewise, if you add then revert something, both can be removed. Or if you bump a dependency to version 2.0.5, then a couple days later go to 2.0.6, you don't need to mention the 2.0.5 one at all. For me personally, this is just part of the process of how I go from git history and PRs to actual user-facing release notes (that have "why", context, and are sorted by added vs fixed, and have callouts of deprecations or breaking changes). But there's a case for it being its own output, or even the only output.
0x457 2y ago
I mean, if you treat commits as a line in changelog and write them that way, then the difference in outputs between autogenerated changelog and what you're talking pretty much goes away. CC style can easily be enforced automatically, I often just rewrite commit messages when merging PRs from contributors, so it looks nice when I run git-cliff on it. You can always add a pre-face by hand to what was generated for every release.
campbel 2y ago
Our company has several repos with enforced conventions on PR titles (much like this tool demonstrates) which does create some pretty decent automatic change-logs. At the very least its easy to get a summary from the list of PRs included in a release. Definitely better than just a git diff. That said, there is no panacea, and there is definitely annoyance in edge cases that don't quite fit.

by nickcw 2y ago

lloydatkinson 2y ago

Did you look at the example changelogs git-cliff creates? > I try to put the important things first in the changelog and keep it brief. The changelog is a heads-up for users that things have changed or been fixed and users don't want to spend hours reading it. Provided the commits use conventional commit format such as "feat(thing): fixed crash when copying file to xyz backend" or "fix(database): generate migrations correctly" not only do you get the type of commit but also the category or area. git-cliff and others then use that to automatically add sections for each category of commit. This wouls surely needing to spend hours on writing changelogs, which seems an insane amount of time to me. > I also spend maybe an hour each release editing the auto generated changelog, removing the noise (refactored X, fixed docs for Y, made tests for Z work), condensing multiple entries, reorganizing, moving things to the correct section, linking stuff etc.

martypitt 2y ago
> Did you look at the example changelogs git-cliff creates? This isn't easily discoverable from the landing page -- I think the site could benefit from an "examples" sections. Given the focus on customizability, it'd be good to get a sense of what's possible, rather than diving straight into Get Started, before I've decided that I want to use the tool.
mathstuf 2y ago
I find that conventional commit wastes space in the summary for little gain. Categories are subjective and just not worth discussing much of the time. Even with it, how do you deal with things like reverts to commits that shouldn't be mentioned in the changelog anymore? Updating text or copy is also annoying. I've found that storing changelog snippets in the repository is far more scalable (one file per note in a directory). This allows future changes to update changelog entries and reverts to just remove them completely. There's also enough trouble getting Github and GitLab to support commenting on commit messages (something they should do anyways!) that feedback on release notes stuffed into commit messages is then a third-class process. They can still be collated and gathered just like from the commit messages, but they're actually tracked by git and there's no confusion when backporting changes: the release note comes with it without having to merge with conflict notes, `cherry-pick -x` notes, etc. You're also not limited to a measly single line for describing your change.
- teeray 2y ago
  > I find that conventional commit wastes space in the summary for little gain The things that conventional commits adds to commits were intended to be accomplished by commit trailers (Co-authored-by, Signed-off-by, etc.). Nobody is stopping anyone from having a “Change-type” trailer and a “Product-area” one too. You can have these in a template on your machine so it’s the same amount of typing involved. You can even tack on `--trailer` to `git commit` if you insist on using `-m` for everything and never filling out the commit body (commits devoid of detail are another plague on repositories).
  - keybored 2y ago

whoomp12342 2y ago

if you start your work under a branch to match a card issued by product (through your sprint/kanban ticket system), then rebase all your commits into that branch, which is what becomes part of that then it CAN be user digestable.

madeofpalk 2y ago

Automated changelog generation tools usually have a mechanism to allow you to opt commits in or out of the changelog. So you still get authorial control over the changelog, but when it comes to actually creating the document it’s automated because you wrote the individual lines when you wrote the code. It’s basically the same as what you’re doing, but in a different order.

remram 2y ago
That works if commits can be looked at in isolation to build the changelog. What if a commit introduces a feature, and a subsequent one changes it? Is there a syntax for your commit to replace an earlier changelog entry? Cue the Kubernetes release notes, which contain 20 separate "update to Go x.y.z" for each release.
- madeofpalk 2y ago
  The way I've always done it is that it's controlled via labels on PRs. If you want to remove a PR (and by swashing merges). If you want to remove a PR from the changelog, remove the label.

stusmall 2y ago

I've been recently working on the process to improve this at my day job. A coworker made a point to make very clear distinction between change logs and release notes, and its made a huge difference in how I approach and think about the problem. A changelog is a raw, engineering driven manifest of everything that has changed. This log sometimes needs more context. Okay the wizbang had a hoozit added, what the hell does this mean and why do I care? Or it needs less and a lot of the engineer rambling needs to be stripped out. The changelog is an input to a release notes process. This is where refine the wording and fix it up for end user consumption. Having a clear changelog pointing back to individual PRs and engineers lets us go back and talk to folks and clean things up and have final wording checked. There is no amount of automation that can every replace this process. It's part of the finishing touches and craftsmanship our customers expect. Nothing I'm saying here is any different than what you are saying. My changelogs are the same as your drafts. I just found having those clear definitions and separate terms made it easier to sell the process and have people understand the big picture.

OJFord 2y ago
> A changelog is a raw, engineering driven manifest of everything that has changed. This log sometimes needs more context. Okay the wizbang had a hoozit added, what the hell does this mean and why do I care? Or it needs less and a lot of the engineer rambling needs to be stripped out. With that definition it literally is just the git log though isn't it, which was GP's point? I know you're writing in agreement, but it sounds like your changelog is an intermediary step, and I don't understand why it's needed? To fill in the gaps from lazy commit messages?
- gregmac 2y ago
  > With that definition it literally is just the git log though isn't it I think you're right if you go by that definition ("changelog is a raw, engineering driven manifest of everything that has changed"), but there I think there is an intermediate step between git log and the user-facing release notes, whether or not it's formalized, which is to basically squash the messages into the list of effective changes since another point-in-time (eg: last release). Let's say you add a feature, then refactor it a bit, then fix a bug in that new code. The only thing that needs to be there is the "Added a feature" part, because the rest is meaningless noise when you compare it to the prior release. Likewise, if you add then revert something, both can be removed. Or if you bump a dependency to version 2.0.5, then a couple days later go to 2.0.6, you don't need to mention the 2.0.5 one at all. For me personally, this is just part of the process of how I go from git history and PRs to actual user-facing release notes (that have "why", context, and are sorted by added vs fixed, and have callouts of deprecations or breaking changes). But there's a case for it being its own output, or even the only output.

0x457 2y ago

I mean, if you treat commits as a line in changelog and write them that way, then the difference in outputs between autogenerated changelog and what you're talking pretty much goes away. CC style can easily be enforced automatically, I often just rewrite commit messages when merging PRs from contributors, so it looks nice when I run git-cliff on it. You can always add a pre-face by hand to what was generated for every release.

campbel 2y ago

Our company has several repos with enforced conventions on PR titles (much like this tool demonstrates) which does create some pretty decent automatic change-logs. At the very least its easy to get a summary from the list of PRs included in a release. Definitely better than just a git diff. That said, there is no panacea, and there is definitely annoyance in edge cases that don't quite fit.