[HN Gopher] Git-cliff - Generate changelog from the Git history
___________________________________________________________________
Git-cliff - Generate changelog from the Git history
Author : orhunp_
Score : 190 points
Date : 2024-06-26 10:43 UTC (2 days ago)
(HTM) web link (git-cliff.org)
(TXT) w3m dump (git-cliff.org)
| amar-laksh wrote:
| Not sure about anything else, but love the animation!
| weinzierl wrote:
| Then you should check out ratatui.rs (different project, same
| author) and maybe its presentations on yt for more awesomeness
| of that kind.
| dkga wrote:
| Amazing animation (and idea) indeed, as someone who loves
| using the terminal and sometimes - only sometimes - like to
| see something new like this.
| esafak wrote:
| This is the kind of thing LLMs are great at.
| dewey wrote:
| That's what I thought when I read the headline but when I
| checked it looks like it's regex based.
| Raptor95 wrote:
| Nice tool
| herewulf wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| >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 wrote:
| 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 wrote:
| 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 wrote:
| > 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 wrote:
| 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/
|
| [2] https://slack.com/intl/en-gb/release-notes/mac
| tjoff wrote:
| > _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 wrote:
| Some projects make it work, see the ratatui.rs example in
| another comment.
| tjoff wrote:
| ratatui.rs is a library, whoever reads that changelog are
| potentially interested in the nitty gritty details. But
| I'd say it is the exception rather than rule, and even in
| that case it is only sensible for projects of a certain
| size with a certain release cadence.
|
| Still, stuff like: 7a48c5b (cell) Add
| EMPTY and (const) new method by @EdJoPaTo in #1143
| This simplifies calls to `Buffer::filled` in
| tests.
|
| feels questionable to have in the changelog either way.
| Unless that for some reason has a great impact for users
| (could be, didn't read into it).
|
| A better example, in my eyes, is teamcity.
|
| https://www.jetbrains.com/help/teamcity/what-s-new-in-
| teamci...
|
| A curated overview that actually explains the change
| rather than just states a difference.
|
| They also have a similar view of fixed tickets: https://w
| ww.jetbrains.com/help/teamcity/teamcity-2024-03-rel...
|
| Doing what teamcity does takes some effort. And I guess
| my gripe is the belief that these conventional commits
| will save the majority of work of the release notes. It
| can be a convenience but it needs curation and work to be
| presentable. And most projects seem to pick them to avoid
| that work.
| keybored wrote:
| > 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].
|
| My knee-jerk reaction is that now we're just inventing
| something to sandwich in-between two already existing and
| useful things: the git log and the curated end-user change
| documentation.
| onion2k wrote:
| I don't quite understand the use case for this sort of app
| (generating a nice changelog from a well structured commit
| history.) In my experience if your team is disciplined enough to
| use something like Conventional Commit rigorously you don't
| actually need an app. The history of the merge commits or pull
| request descriptions is usually enough, unless you're passing the
| changelog to particularly non-technical users, in which case you
| need a human to write the changelog regardless.
|
| For an app to be useful you need to have a case where you want
| the data from the commit history to be useful in the context of a
| doc, where you retain technical descriptions written by devs.
| Just copying the commit descriptions into a doc, even in a nicer
| format, feels like theatre to me. You aren't gaining anything.
| Non-technical users won't benefit from it and everyone else can
| learn 'git log'.
|
| There is an arguement that using this would push a dev team to
| improve their commits, but in my experience if the team lack
| enough discipline to write them well a time saving tool isn't
| enough to push them to get better. They're probably not writing a
| useful changelog yet, so this doesn't save any time at all.
|
| I really hope I'm missing something.
| CGamesPlay wrote:
| > Just copying the commit descriptions into a doc, even in a
| nicer format, feels like theatre to me. You aren't gaining
| anything. Non-technical users won't benefit from it and
| everyone else can learn 'git log'.
|
| I disagree. As a technical user who consumes many external
| repositories, I much prefer reading a changelog to reading a
| list of commits. First, I'm not reading this in a git client;
| I'm reading it in a web browser (likely on Github). In this
| interface, being able to see via headings the changes since my
| current version and the new version is extremely useful.
| Second, the change log is distributed with the application,
| even in cases where the source code isn't (this is especially
| useful when thinking about things like GUI auto-update checks,
| where I want to see the change log before I decide to upgrade).
| Third, the one-line summaries typically link back to commits or
| PRs, so when I see something I do want more information about,
| I can easily find the technical discussion about it.
| Jochim wrote:
| I think it serves a few potential purposes:
|
| It provides a solid, accurate draft that can be expanded on
| when targeting non-technical users.
|
| I've often found that lack of visibility leads to messy
| commits. Surfacing these messages in the changelog introduces
| an incentive to take more care.
|
| With regards to the usefulness of the descriptions, the
| associated issue is often linked along with the commit message.
| This is often omitted in hand-written changelogs. In this case
| the auto-generated changelog acts as an index, allowing the
| reader to quickly parse what changed and jump to the associated
| code or ticket.
| lloydatkinson wrote:
| > I don't quite understand the use case for this sort of app
| (generating a nice changelog from a well structured commit
| history.) In my experience if your team is disciplined enough
| to use something like Conventional Commit rigorously you don't
| actually need an app.
|
| > Just copying the commit descriptions into a doc, even in a
| nicer format, feels like theatre to me. You aren't gaining
| anything. Non-technical users won't benefit from it and
| everyone else can learn 'git log'.
|
| > I really hope I'm missing something.
|
| Yes, this seems to be cynical for the sake of cynicism. The
| point of tools like this is that you do in fact want this
| document, because no one will be copy pasting messages from git
| log to put in the changlog files. And if they are, they would
| appreciate a tool to do it for them.
|
| Additionally, changelogs are part of releases and will show up
| in GitHub releases, package managers, etc.
| e12e wrote:
| Going through prs generated by GitHub dependabot - I very much
| appreciate projects that provide release notes/change logs that
| highlight breaking changes. It would require a lot of work to
| go through each individual project for actual commit history
| between foo v1.2.4 and v1.3.2.
|
| Now you could argue that one _should_ look at all dep code
| changes... But it 's a tall order to fully audit all
| dependencies.
| fphilipe wrote:
| I am definitely more in the changelog-as-a-file camp. From
| https://keepachangelog.com/:
|
| > 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.
|
| > The purpose of a commit is to document a step in the evolution
| of the source code. Some projects clean up commits, some don't.
|
| > The purpose of a changelog entry is to document the noteworthy
| difference, often across multiple commits, to communicate them
| clearly to end users.
| pydry wrote:
| Noise can be excluded.
| airtonix wrote:
| spent 3 years on a team hoping they would step up a write
| meaningful changeset titles...
|
| however. ended up just getting:
|
| - fixed things. - creates new feature x - fixed broken thing.
|
| instead of something that's appreciable by non technical
| people:
|
| - when navigating to the nuclear launch code dashboard, a user
| is no longer mocked for having a likeness to <current unpopular
| person>.
|
| point here is. if your team didn't write good squash merged PR
| titles before, they won't magically start doing so because
| you're using changesets.
| nsbk wrote:
| Me too, but some tools combine the best of both worlds. In my
| team we use commitizen [1] which drinks both from
| keepachangelog and conventional commits and we are quite
| pleased with our changelogs so far.
|
| [1] https://commitizen-tools.github.io/commitizen/#features
| WorldMaker wrote:
| > they're full of noise. Things like merge commits
|
| From another angle, merge commits can also be a _solution_ to
| the problem. `git merge --no-ff --edit` can be a great way to
| summarize an entire branch of commits. Most PR tools will give
| you an easy way to create those kind of merge commits. Don 't
| settle for the default "merge branch x into y", create a
| meaningful title and fill in details/summary of what happened
| in the branch. With traversal tools like git log --first-parent
| you can see a high level of just your merge commits with the
| gnarly details of whatever steps led up to the merge commit
| itself.
|
| I've certainly seen good projects where `git log --first-
| parent` was always a useful first pass changelog (no matter how
| "clean" the rest of commits were or were not). Probably still
| not a changelog you should send as a document to end users
| (because still written from a development standpoint rather
| than a user standpoint), but a good place to start writing the
| end user documentation.
| CGamesPlay wrote:
| I'm pretty unclear on what the "bump" command does. Does this
| create a git tag? Make a new commit? Have hooks to update version
| constants in the source? Seems like the answer to all of these is
| "no", and so I'm not really sure how useful it is.
|
| I'm also aware of related tool in this space: semantic-release
| <https://github.com/semantic-release/semantic-release>. I haven't
| used it in my repositories, but it seems like a more
| comprehensive verison of git-cliff.
| the_duke wrote:
| What other comments are missing is that git-cliff is based on the
| conventional commits [1] spec.
|
| If you follow this properly the commits will already have
| important metadata for presentation in a changelog.
|
| Also keep in mind that the auto-generated changelog should always
| be augmented and filtered manually before the final release.
|
| But the combination of git-cliff and conventional commits can
| save a lot of time for the initial draft.
|
| It does require discipline in using conventional commits
| properly.
|
| [1] https://www.conventionalcommits.org/en/v1.0.0/
| wdroz wrote:
| You can use conventional pre-commit[0] to validate that commit
| messages follow the convention and use only the types that the
| team agreed upon.
|
| This still requires discipline to choose the "right" type and
| scope.
|
| [0] -- https://github.com/compilerla/conventional-pre-commit
| mihaaly wrote:
| > If you follow this properly
|
| There it goes! One more thing to do precisely and not only at
| dedicated time but continuously on top of all other things to
| do precisely already inherently around completing a task.
| Everyone all the time think about the state of changelog
| communication in addition, and do it well, phrase it for
| changelog purposes, format it for that as well. While working
| on changelog on the end will need additional work still.
|
| In some simple situation it may have merit though, I admit.
| Seems like additional trouble (both workload and source of
| mistakes) in a medium to large team.
|
| Except if the developers are well programmed robots themselves,
| of course, those do not fail (or easy to throw out and replace
| if they do).
| lloydatkinson wrote:
| If a team of devs is incapable of writing good commits with
| simple prefixes then that's a strong case for adding git
| hooks that reject commits without the prefix.
|
| Before someone starts getting their pants in a twist at this
| idea, you can configure a solution such that commits to
| branches don't need a conventional commit format, but that
| the commit that merges a PR into master must have
| conventional commit format.
| mihaaly wrote:
| In an idealized and simplistic (imaginary) world you are
| completely right, but here you missed the point quite a
| bit:
|
| People make mistakes! Everyone! Already.
|
| More things to watch for and take care of, with more
| people: more mistakes.
|
| Too much mistakes - that we already have without more
| aspects - negate the advantages of the idealized intended
| outcome.
|
| People working with other people in everyday situations
| could understand that.
| Izkata wrote:
| Forget mistakes, such a commit hook would prevent me from
| making small iterative commits. I'd just disable that
| hook within the first few days.
| lloydatkinson wrote:
| > Before someone starts getting their pants in a twist at
| this idea, you can configure a solution such that commits
| to branches don't need a conventional commit format, but
| that the commit that merges a PR into master must have
| conventional commit format.
| shepherdjerred wrote:
| You can skip pre-commit hooks with the --no-verify flag
|
| https://git-scm.com/docs/git-commit#Documentation/git-
| commit...
| keybored wrote:
| > Before someone starts getting their pants in a twist at
| this idea, you can configure a solution such that commits
| to branches don't need a conventional commit format, but
| that the commit that merges a PR into master must have
| conventional commit format.
|
| Not can, must. You cannot enforce this for local
| development since git(1) doesn't allow project-wide hooks
| for security reasons.
| lloydatkinson wrote:
| I don't know where you're getting this but there are in
| fact many tools for local commit hooks
| https://typicode.github.io/husky/
| sloowm wrote:
| The other option is someone scouring through the mess of
| commits to find out what should be in the changelog or you
| have to update the changelog with each commit to the main
| branch. Which brings you back to the extra step on top of
| things you need to do.
|
| So this is a way to reduce overhead, you need to write a
| commit message anyway so why not reuse that effort.
|
| "Simple" projects like curl use their commit messages for the
| changelog.
| lolinder wrote:
| > But the combination of git-cliff and conventional commits can
| save a lot of time for the initial draft.
|
| Does it though? What would happen if we instead directed our
| discipline into updating the changelog manually on each PR?
|
| Does having git cliff as the middleman provide much value if I
| have to enforce highly specific logging practices in the PR
| anyway?
| ddulaney wrote:
| We built an internal system that grabs our git history. For each
| commit you either enter a release note or mark it as not customer
| facing. It's worked pretty well so far: each developer runs
| through their list writing down something, and a technical writer
| follows up checking style and grammar. We have confidence that
| every commit was at least looked at.
|
| We do monthly releases, and the level of effort has been under an
| hour each month per dev, which has been super worth it for us.
| Jochim wrote:
| I've seen the same thing done within the ticketing system. It's
| useful when you might want non-developers to contribute to the
| notes.
|
| Being able to dedicate a tag, field, or work item type is
| pretty handy.
| weinzierl wrote:
| We considered generating the changelog from the git commits,
| the information contained in the PR and from the ticket.
|
| Ultimately we also decided to go with the tickets, but I am
| curious what your reasoning was to go that way?
| Jochim wrote:
| Sadly, we didn't end up implementing it ourselves. Release
| notes were a "nice to have" so it became one of those
| things that gets kicked down the road.
|
| The primary advantage of the ticket-based approach is that
| it's much easier to involve non-dev stakeholders. I'd
| choose it whenever other people might want input in the
| process. Most ticketing systems also offer a lot of
| flexibility, you could incorporate the ticket name, group
| tickets by relation, block completion states, act on
| deployments, etc. The ability to edit the note without
| rebasing is a major bonus as well.
|
| The git-based approach potentially leads to a more readable
| commit history, and strongly associates any release notes
| with the actual code change. On the other hand, it's a pain
| to edit and can distract devs while they're problem solving
| if not setup well.
| ddulaney wrote:
| The reason I didn't go with a ticket-based approach is
| that we don't have a perfect 1-to-1 mapping of commits to
| tickets. The worry was that we would miss commits because
| they weren't well-associated. Because the tool we made is
| web-based, it's a little less scary for non-devs.
| keybored wrote:
| It grabs the history? So it is written after the fact (after
| the commit message)? Where is it stored?
| ddulaney wrote:
| It stores it in a "branch" that's totally separate from the
| main branch, kinda like git-notes. We push that branch to our
| git forge like normal, so there are copies of it all over the
| place, and we can make a CLI tool if we ever want to.
|
| It works really well so far.
| keybored wrote:
| That's cool that you make it separate from the commit
| message and yet linked to it.
|
| We also might need customer facing release notes at some
| point. But that shouldn't be in the commit messages I think
| since it's irrelevant in that technical context.
| pavlov wrote:
| I can't help it, my mind reads this name as a spoonerism:
|
| https://en.wikipedia.org/wiki/Spoonerism
|
| "The GIF search tool that finds it", perhaps.
| joshka wrote:
| Here's an example of a changelog that is generated using git-
| cliff: 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/
| weinzierl wrote:
| The changelog is completely generated with no manual editing
| afterwords, right? In the same vein, is the highlights doc
| written by a human?
| keybored wrote:
| 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).
| mattrighetti wrote:
| I've been using cocogitto[0] which also generates changelog, also
| based on Conventional Commits. Plus, it has some nice features
| such as pre/post-bump hooks.
|
| [0]: https://github.com/cocogitto/cocogitto
| nickcw wrote:
| 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/
|
| 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/ 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 wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| > 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 wrote:
| Yes, trailers are built-in and serve the metadata purpose
| in a fair amount of projects already.
|
| There's also more freedom to be verbose ("Change-For-
| Downstream-X") since they are at the very bottom of the
| commit message. You can even filter out certain trailers
| with git log.
|
| The Conventional Commits people were apparently not aware
| of this capability when they started (understandable
| since the tooling is niche). You can see they had some
| back and forths about trying to get their "footers" in
| line with trailers and how they had to stumble across
| misunderstandings about how they work.
| parasti wrote:
| > I've found that storing changelog snippets in the
| repository is far more scalable (one file per note in a
| directory).
|
| Do you have an example repo that you can share? This sounds
| really ideal but wondering how this is managed and
| organized between releases.
| mathstuf wrote:
| See https://gitlab.kitware.com/cmake/cmake/-/tree/master/
| Help/re... for where CMake stores its "release snippets".
| There's a template file to anchor the directory and serve
| as an example. At each release, the directory is emptied
| out and release notes put into sorted order and edited
| for consistency/clarity.
| whoomp12342 wrote:
| 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 wrote:
| 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.
| stusmall wrote:
| 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 wrote:
| > 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 wrote:
| > 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.
| R0flcopt3r wrote:
| We give support a change log, the customer a release note.
| Developers use the git log.
| Sayrus wrote:
| When using open source tools, I love having a change log
| with direct links to merge requests and issues, and
| potentially across several repositories. It makes the
| process of reviewing and searching for changes so much
| easier than pulling the log.
|
| It's also great to ship that changelog with the artifacts
| so they are readable on third-parties (Helm Charts on
| Artifacthub, GitLab and GitHub releases, ...).
| stusmall wrote:
| >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?
|
| It's about the audience.
|
| * Commit Messages - These are comments that last for the
| life of the project. The audience in for engineers far in
| the future and it should explain what changed, why and the
| context
|
| * Pull Request Message - These are comments that live for a
| short time and are targeted for reviewers. Things you might
| cover here that aren't covered in a commit message is what
| kind of manual tests were done, releases you want to
| target, or reference other PRs that might be related
|
| * Changelog entry - These audience here is internal. It is
| SREs, release managers and the authors of the release notes
|
| * Release notes - This is for the customers
|
| For many changes, all of these can be the exact same thing.
| It's one reason why I like conventional commits. In those
| cases you can write it once and it shows up everywhere with
| very little friction. You add it to the commit message,
| then when you open the PR the title and body are populated
| from the commit. When you generate changelogs, it is pulled
| from git history. Engineering isn't always the happy path,
| for special situations in each one of those steps you can
| edit it and add or remove context for the particular
| audience.
|
| Not all orgs need this or need to care about it. It's
| completely okay if they don't. I've just found it useful in
| mine.
| 0x457 wrote:
| 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 wrote:
| 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.
| lloydatkinson wrote:
| I'm not involved with this, but I did create the winget-pkgs
| issue to get git-cliff available for use on Windows.
|
| Because of this Windows users can simply run "winget install git-
| cliff".
|
| Small things like this help with adoption.
| kreetx wrote:
| IMO, changelogs taylored by humans are often better (feel more
| "whole") than machine generated from commit logs. If anyone wants
| to see the commit logs, they are there for inspection, and when
| written well can give a good idea on what has been going on.
| gigatexal wrote:
| Hah mgmt asked for something like this and boom HN provides!
| welpo wrote:
| I use git-cliff for my personal projects. If you follow
| conventional commits and squash merges, you get a clear, user-
| friendly changelog--it's easy to "skip" commits that don't affect
| the end user.
|
| I wrote a tool to validate commits, which helps ensure both the
| git history and changelog look clean:
| https://github.com/welpo/git-sumi
| pseudalopex wrote:
| Repeated items, items irrelevant to users, details irrelevant
| to users in each item, and poor organization in each section
| make the git-sumi release notes unclear and user unfriendly.
| welpo wrote:
| You're right; there is a lot of noise in the git-sumi
| changelog. As it matures (and I tinker less with it), it
| should get better.
|
| Here's a better example on a more mature project:
| https://github.com/welpo/tabi/blob/main/CHANGELOG.md
| pseudalopex wrote:
| The tabi release notes have items irrelevant to users,
| details irrelevant to users in each item, and poor
| organization in each section.
| epage wrote:
| For me, I find this approach better than nothing and would not
| shame or discourage someone from using it over hand written.
|
| That said, I am wanting a Github action based release workflow
| and want it to scale to manual edits of changelogs, so this is
| insufficient for me. Instead, I've been taking notes on changelog
| fragments as I hope they can offer the best of both worlds, see
| https://github.com/epage/epage.github.io/issues/23
| Pawamoy wrote:
| I maintain git-changelog, which is a similar implementation in
| Python (started two years before git-cliff). When I discovered
| git-cliff a few months ago, I was very impressed by the number of
| things they support. Also, being written in Rust, it must be much
| more performant than my Python implementation (which indeed has
| trouble with huge Git histories). I have started recommending
| git-cliff to some of my users who request features I don't yet
| support :)
|
| Great work, git-cliff devs!
| benrutter wrote:
| This looks great! My team does something very similar with a key
| project but more home-spun because git-cliff either didn't exist
| or wasn't known about at the time.
|
| For everyone saying "manually written changelogs are so much
| better" - well, yeah of course! But they also take up a lot more
| time and resource to curate. I'd hate to see a huge project like
| gnome or something do this, but I don't think that's the pitch.
|
| As an alternative for either a badly maintained changelog, or no
| changelog at all, adopting commit or PR conventions is a great
| idea.
| dkga wrote:
| ... it's me, Cathy...
| quesera wrote:
| I cannot justify upvoting this comment, but I will thank you
| for bringing a smile to my day.
| lucasoshiro wrote:
| ... I've come ~
| nixpulvis wrote:
| 16 clicks to get to the examples in the documentation. I think
| you could do a much better job of organizing and showcasing how
| this tool works before so much about how to install it on every
| platform.
| schneems wrote:
| Here's my solution: I have a github action that checks if the
| changelog was touched in the diff. It fails tests if not.
|
| It's impossible to rewind your brain to the time of when the
| change is made to consider the total impact to the end user. The
| best time to write a changelog is when the change happens.
|
| For minor stuff that doesn't need to be in the changelog, the
| action checks a label and passes if "skip changelog" is applied.
| But the default is "hey, you forgot to tell users what they
| should expect with your change"
| keybored wrote:
| I hope I don't have to work in a project with Conventional
| Commits.
|
| - The mandatory formatting takes up prime real estate in the
| subject line
|
| - You don't get much data out of it: one byte (rounded up) since
| it's just "type" and "is breaking change or not". Not a great
| trade considering how much it sticks out
|
| - It subjectively looks bad: "feat", "chore", codey exclamation
| mark (punctuation) for breaking changes, and BREAKING CHANGE in
| all-caps (it's supposed to be machine readable so why shout, your
| programs are supposed to pick up this for you)
|
| - You have to care about this for every final commit that lands
| in the project
|
| - Just to serve a changelog (which is supposed to just ape the
| git log?)
| jasonpeacock wrote:
| > You have to care about this for every final commit that lands
| in the project
|
| Same as having a standard coding style, you should have a
| standard commit message style that you _do_ care about for
| every commit in the project. A mish-mash of variable quality
| and variable formatted commits more than subjectively looks bad
| - it reduces the signal-to-noise of the commit messages.
|
| As for the `feat(scope):` in the subject line, it's a very
| succinct way to communicate the type of the change. Don't make
| me the read the whole commit to figure out if this was a
| feature or bug fix, or only affected the build.
|
| > Just serve a changelog
|
| Sure. But I want the changelog to list features first, then bug
| fixes, etc. How do I do that automatically with only the git
| log w/o some sort of standardized tagging of the commits?
| keybored wrote:
| > Same as having a standard coding style, you should have a
| standard commit message style that you do care about for
| every commit in the project. A mish-mash of variable quality
| and variable formatted commits more than subjectively looks
| bad - it reduces the signal-to-noise of the commit messages.
|
| I already personally use a standard commit message style.[1]
| And that standard is about how to structure the prose, not
| about using any kind of structured markup (outside the
| trailers section).
|
| > As for the `feat(scope):` in the subject line, it's a very
| succinct way to communicate the type of the change. Don't
| make me the read the whole commit to figure out if this was a
| feature or bug fix, or only affected the build.
|
| Verbs already serve that purpose most of the time. Then you
| get redundant lines like `feat: add OAuth 2.0 login`.
|
| > Sure. But I want the changelog to list features first, then
| bug fixes, etc. How do I do that automatically with only the
| git log w/o some sort of standardized tagging of the commits?
|
| If you have such a high volume of commits (that users would
| care about) that you have have distribute tagging of all
| commits to all contributors,[2] you can use the trailers
| section.[3]
|
| [1] I don't expect anyone else to at work. In one free-time
| project people use the same style, with one exception
| (against my personal taste).
|
| [2] And if you need such a detailed changelog, let alone a
| fully automatically written one
|
| [3] https://news.ycombinator.com/item?id=40820213
| vzaliva wrote:
| This may be a task where LLM (AI) could do a reasonable job. Of
| course the results need to be reviewed by a human.
| sigmonsays wrote:
| this is a great tool, I dont think it replaces maintaining a
| proper changelog but it definitely helps track what is added to
| each release.
|
| I think there should be both a generated changelog and an
| official changelog when a release is made.
| whoomp12342 wrote:
| maybe I'm basic but I'd rather just use git to do this and not
| conform to a specific tooling / format
| habosa wrote:
| Just want to say that the animation on the home page is
| delightful and a lot more creative than you'd expect from a git
| tool.
| pheatherlite wrote:
| Wip Wip Wip ...
| gradientsrneat wrote:
| git-shortlog, which is built in to git, can also write
| changelogs, with support for arbitrary grouping based on commit
| metadata.
___________________________________________________________________
(page generated 2024-06-28 23:01 UTC)