3 ms·

Here's an example of a changelog that is generated using git-cliff: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md https://github.com/ratatui-org

by joshka 2y ago

Here's an example of a changelog that is generated using git-cliff: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.m... The things that make this work well for us are - We make sure we document every PR with user facing language and conventional commits. - We generally use GitHub's squash merge, which means the noisy development commits are not part of the changelog. - We create a highlights doc when we release that summarizes the main points of the changelog (this is the distinction between a changelog and release notes). E.g. https://ratatui.rs/highlights/v027/ https://ratatui.rs/highlights/v027/

weinzierl 2y ago
The changelog is completely generated with no manual editing afterwords, right? In the same vein, is the highlights doc written by a human?
- joshka 2y ago
  yes and yes
keybored 2y ago
It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). It looks nice. And verbose. Like a lot of refactoring bullet points. The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands).
- joshka 2y ago
  > It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). Yeah pretty much. The config is at https://github.com/ratatui-org/ratatui/blob/main/cliff.toml https://github.com/ratatui-org/ratatui/blob/main/cliff.toml > It looks nice. And verbose. Like a lot of refactoring bullet points. Most of the bullet points are single features / changes to the library that are delivered to the users of the library. > The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). Can you give an example of this? Everything you're seeing in the changelog is a commit that has been pushed to the repo with a title message and a manually crafted body - we generally avoid letting the body be the github squash commit PR message junk. > In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands). Yeah, and that's generally useful from the perspective that it's available online, searchable in a single doc (which makes it easy to answer questions like "when was blah implemented" There's probably a bunch of things that would make this even better, but there's diminishing returns on the effort involved in doing so.
  - joshka 2y ago
    I see what you mean about the squashed commits now. I've updated the template we're using to make this a little nicer now - https://github.com/ratatui-org/ratatui/blob/5e7fbe8c328050a282a49b8c6ab3f5b33c7cfb4c/CHANGELOG.md https://github.com/ratatui-org/ratatui/blob/5e7fbe8c328050a2... (from an in flight PR)
sendfoods 2y ago
One question - how are you able to generate links to the commits, by hash?
- joshka 2y ago
  Yes. See https://github.com/ratatui-org/ratatui/blob/main/cliff.toml#L29 https://github.com/ratatui-org/ratatui/blob/main/cliff.toml#...

by joshka 2y ago

weinzierl 2y ago

The changelog is completely generated with no manual editing afterwords, right? In the same vein, is the highlights doc written by a human?

joshka 2y ago
yes and yes

keybored 2y ago

It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). It looks nice. And verbose. Like a lot of refactoring bullet points. The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands).

joshka 2y ago
> It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). Yeah pretty much. The config is at https://github.com/ratatui-org/ratatui/blob/main/cliff.toml https://github.com/ratatui-org/ratatui/blob/main/cliff.toml > It looks nice. And verbose. Like a lot of refactoring bullet points. Most of the bullet points are single features / changes to the library that are delivered to the users of the library. > The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). Can you give an example of this? Everything you're seeing in the changelog is a commit that has been pushed to the repo with a title message and a manually crafted body - we generally avoid letting the body be the github squash commit PR message junk. > In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands). Yeah, and that's generally useful from the perspective that it's available online, searchable in a single doc (which makes it easy to answer questions like "when was blah implemented" There's probably a bunch of things that would make this even better, but there's diminishing returns on the effort involved in doing so.
- joshka 2y ago
  I see what you mean about the squashed commits now. I've updated the template we're using to make this a little nicer now - https://github.com/ratatui-org/ratatui/blob/5e7fbe8c328050a282a49b8c6ab3f5b33c7cfb4c/CHANGELOG.md https://github.com/ratatui-org/ratatui/blob/5e7fbe8c328050a2... (from an in flight PR)

sendfoods 2y ago

One question - how are you able to generate links to the commits, by hash?

joshka 2y ago
Yes. See https://github.com/ratatui-org/ratatui/blob/main/cliff.toml#L29 https://github.com/ratatui-org/ratatui/blob/main/cliff.toml#...