4 ms·

I've seen quite a few projects lately that are generating their release notes from commit history. This is quite bad because it's frequently full of things th

I've seen quite a few projects lately that are generating their release notes from commit history. This is quite *bad* because it's frequently full of things that are inconsequential for users. I really don't care that you refactored your foo-baz into a qux-quz. Please at least summarize the major points between releases. Hopefully this software is better but this seems like an opportune place to lodge this complaint.

Aeolun 2y ago
I disagree. I find it quite useful to see that a refactor happened in the foobar, when my foobar has suddenly stopped working from one release to the next.
- j16sdiz 2y ago
  This is quite useful to narrow down the problem when it occur. This is not useful to decide if I should upgrade now, or what should I try out after upgrade --- and this is what a release note should be doing.
shiroiushi 2y ago
>I've seen quite a few projects lately that are generating their release notes from commit history. This is quite bad because it's frequently full of things that are inconsequential for users. I really don't care that you refactored your foo-baz into a qux-quz. I disagree: I think it's extremely helpful for users to read dozens or even hundreds of commit messages saying "fixed typo". /s
- Jochim 2y ago
  This feels like a fairly disingenuous interpretation of how this gets implemented. Normally, commits must match a particular pattern to be included. Those that start with "feat:" might appear in the features section, while those starting with "bug:" show up in fixes. A few simple rules are enough to ensure that an intelligible changelog is generated. Minimal cleanup can then focus on making it presentable. You could even set up your pull request rules to handle this for you. On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
  - shiroiushi 2y ago
    This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. >On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates. Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)
    - Jochim 2y ago
      > This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. Making snarky comments isn't particularly interesting, nor does it offer much opportunity for discussing the actual benefits/drawbacks of the topic. > Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.) That's an issue with the policies of those specific organisations rather than with the idea of generating a changelog from commit messages. Squashing/Rebasing isn't necessary to generate a clean changelog. You don't need to include every commit by default.
weinzierl 2y ago
I don't disagree in general, but I think "because it's frequently full of things that are inconsequential for users" should not be a good reason. The idea behind auto-generating the changelog with a tool like git-cliff is to use it in conjunction with conventions on your commit messages like Conventional Commits [1]. This gives you fine grained control about what will appear in the changelog. What you do, is to move the decision whether some information ought to appear in the changelog from the time of release to the time of the commit. You also shift the responsibility from the release manager to the individual developers. The big advantage of this process is that it is much harder to forget to include things. If that is a good idea depends on your project and team. For open source projects, where everything is public anyways, the generated changelog could act as a pretty-printed, filtered and limited view of the git history. For proprietary software I believe the commit messages should be a space where the developers can express themselves without having to worry about that anything they write could end up at the customer (which I presume is the ultimate consumer of the changelog). I also think there is a difference between a changelog and release notes with the former not being a replacement for the latter. For a good example how in my opinion useful release notes could look like see [2]. Apart from all of that git-cliff is an excellent implementation. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [2] https://slack.com/intl/en-gb/release-notes/mac https://slack.com/intl/en-gb/release-notes/mac
- tjoff 2y ago
  >What you do, is to move the decision whether some information ought to appear in the changelog from the time of release to the time of the commit. Which doesn't make any sense. 20 commits/PRs might fit together in as one line in the changelog. There is nothing that one can write in any one of those commits that make any sense at the time of commiting.
  - weinzierl 2y ago
    Some projects make it work, see the ratatui.rs example in another comment.
    - 2y ago

I've seen quite a few projects lately that are generating their release notes from commit history. This is quite *bad* because it's frequently full of things th

Aeolun 2y ago

I disagree. I find it quite useful to see that a refactor happened in the foobar, when my foobar has suddenly stopped working from one release to the next.

j16sdiz 2y ago
This is quite useful to narrow down the problem when it occur. This is not useful to decide if I should upgrade now, or what should I try out after upgrade --- and this is what a release note should be doing.

shiroiushi 2y ago

>I've seen quite a few projects lately that are generating their release notes from commit history. This is quite bad because it's frequently full of things that are inconsequential for users. I really don't care that you refactored your foo-baz into a qux-quz. I disagree: I think it's extremely helpful for users to read dozens or even hundreds of commit messages saying "fixed typo". /s

Jochim 2y ago
This feels like a fairly disingenuous interpretation of how this gets implemented. Normally, commits must match a particular pattern to be included. Those that start with "feat:" might appear in the features section, while those starting with "bug:" show up in fixes. A few simple rules are enough to ensure that an intelligible changelog is generated. Minimal cleanup can then focus on making it presentable. You could even set up your pull request rules to handle this for you. On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
- shiroiushi 2y ago
  This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. >On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates. Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)
  - Jochim 2y ago
    > This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. Making snarky comments isn't particularly interesting, nor does it offer much opportunity for discussing the actual benefits/drawbacks of the topic. > Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.) That's an issue with the policies of those specific organisations rather than with the idea of generating a changelog from commit messages. Squashing/Rebasing isn't necessary to generate a clean changelog. You don't need to include every commit by default.

weinzierl 2y ago

I don't disagree in general, but I think "because it's frequently full of things that are inconsequential for users" should not be a good reason. The idea behind auto-generating the changelog with a tool like git-cliff is to use it in conjunction with conventions on your commit messages like Conventional Commits [1]. This gives you fine grained control about what will appear in the changelog. What you do, is to move the decision whether some information ought to appear in the changelog from the time of release to the time of the commit. You also shift the responsibility from the release manager to the individual developers. The big advantage of this process is that it is much harder to forget to include things. If that is a good idea depends on your project and team. For open source projects, where everything is public anyways, the generated changelog could act as a pretty-printed, filtered and limited view of the git history. For proprietary software I believe the commit messages should be a space where the developers can express themselves without having to worry about that anything they write could end up at the customer (which I presume is the ultimate consumer of the changelog). I also think there is a difference between a changelog and release notes with the former not being a replacement for the latter. For a good example how in my opinion useful release notes could look like see [2]. Apart from all of that git-cliff is an excellent implementation. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ [2] https://slack.com/intl/en-gb/release-notes/mac https://slack.com/intl/en-gb/release-notes/mac

tjoff 2y ago
>What you do, is to move the decision whether some information ought to appear in the changelog from the time of release to the time of the commit. Which doesn't make any sense. 20 commits/PRs might fit together in as one line in the changelog. There is nothing that one can write in any one of those commits that make any sense at the time of commiting.
- weinzierl 2y ago
  Some projects make it work, see the ratatui.rs example in another comment.
  - 2y ago