3 ms·

While auto-generated changelogs aren't the best, they are better than nothing. Too often I've seen projects without a changelog which is especially annoying wh

by epage 5y ago

While auto-generated changelogs aren't the best, they are better than nothing. Too often I've seen projects without a changelog which is especially annoying when dealing with breaking changes. I've been considering switching to a changelog generator, either from Conventional Commits or from a folder of files just to avoid merge conflicts with the CHANGELOG file. If people want enforcement of Conventional Commit, check out https://github.com/crate-ci/committed https://github.com/crate-ci/committed

rkeene2 5y ago
What I do is include the ChangeLog in the tag for the release. I do semi-manually generate the ChangeLog using the titles of the Story/Bug that was merged in for a given PR, and then any commits that were done directly get a special notation (if any exist). The list of Stories/Bugs is generated automatically (branch->PR->Story). This way there is no ever growing file, but the ChangeLog is available for every release within the VCS, and it's organized by release.
krick 5y ago
I work with projects where this is utilized and I'm not sure they are better than nothing. Maybe I will change my mind someday, but up to this point, "conventional commits" are the stupidest thing ever. First off, this is not really a convention, more like a pretentious attempt to invent one: they are really bad defined and it isn't really clear when one or the other prefix should be used. As a result: if you are working alone (or your only teammate has very a mindset similar to yours), you won't need it, it will be just inconvenient. If you have a team of developers with various experiences and habits that need a convention to be enforced, it will be very hard to evaluate if they use prefixes correctly, let alone if commit messages are any good. The real problem is that commit messages and a changelog serve 2 different purposes and have different audiences. Changelog exists to explain what happened with the product, and commit messages exist to explain what happened with the code. These are the same thing only in the most basic situations, like "change Delete button color to red" (and then you probably don't even want to clutter your changelog with such bullshit at all). So, this works when 1 Jira ticket equals 1 commit. This is not usually the case, and, what's more, this usually shouldn't be the case. If your changelog audience is a project manager, for example, you are better off with generating if from ticket ids that you include into the commits that resolve some task (you don't need and probably don't want that atrocity of "conventional commits" for that). Changelog generated from "conventional commits" is verbose, clunky, sometimes outright false, misses most of important stuff if some things are resolved in libraries. It is simply bad. But arguably better than nothing if there are no tradeoffs. But there are. The real problem is, now your commits are bad as well, because they are completely fucked up in an attempt to shape them into a changelog, which cannot be done effectively. Best case scenario, your commits now completely mirror your tickets and you end up with huge commits, but at least the changelog looks OK-ish. So the tool intended for developers no more is. Anything in between and both your commits and your changelog are messed up.
- lowercased 5y ago
  > it will be very hard to evaluate if they use prefixes correctly, I faced this on a small team that adopted it. From my reading, it's OK if you create some of your own prefixes that suit your workflow. The point is to get everyone to use the same thing, not to try to say "feat/chore/etc" are the only things you can ever use. But... the team I was on didn't want to change anything, just use out of the box defaults, because "these are the community standards" (words to that effect). I do not like being forced in to the "conventional commit" style as it gives the impression that it's providing something of value, when, in our case, it's not really valuable to anyone on the team. I did some other work in 2019 on a different team which was much more efficient and effective with their commits, review, merging, etc, but didn't use conventional commit.
- epage 5y ago
  > I work with projects where this is utilized and I'm not sure they are better than nothing. At least you know which commits caused a breaking change compared to spelunking the history to figure out how a library broke compatibility and how you need to adapt to it. Breaking changes are honestly one of the main reasons I read changelogs. > The real problem is that commit messages and a changelog serve 2 different purposes and have different audiences. Changelog exists to explain what happened with the product, and commit messages exist to explain what happened with the code. imo a commit summary and the start of the body should explain the the goal, the user facing aspect and then should dig down into the whats and whys of how the changed lines support that goal, using Inverted Pyramid / Bottom-line Up Front writing style. Of course, if the commit has no end-user impact, you signify that with the type (feat/fix/etc vs chore/style/etc) While doing a hand-curated changelog for end-users would be more polished, the summary of a commit message should still be passable.
- joshuanapoli 5y ago
  Using pull-request descriptions for the auto-generated change-log helps give more flexibility for authors to describe their work. It's possible to embed media in the PR description. It' easier to encourage ample description in PR descriptions than commit messages. We often want to leave commits at a finer granularity than features, making it hard to leave a coherent story.
nivertech 5y ago
IMO it's a good idea to add a Github Issues label for each conventional commit type and scope: <type>[optional scope]: <description> fix: feat: build: chore: ci: docs: style: refactor: perf: test: etc. Let's say we have following scopes: core, infra, api, runtime. The add label in Github issues for each of them.
- toastal 5y ago
  Not a bad idea, but why would or should adding a label to a Git commit message have anything to do with GitHub?

by epage 5y ago

rkeene2 5y ago

What I do is include the ChangeLog in the tag for the release. I do semi-manually generate the ChangeLog using the titles of the Story/Bug that was merged in for a given PR, and then any commits that were done directly get a special notation (if any exist). The list of Stories/Bugs is generated automatically (branch->PR->Story). This way there is no ever growing file, but the ChangeLog is available for every release within the VCS, and it's organized by release.

krick 5y ago

I work with projects where this is utilized and I'm not sure they are better than nothing. Maybe I will change my mind someday, but up to this point, "conventional commits" are the stupidest thing ever. First off, this is not really a convention, more like a pretentious attempt to invent one: they are really bad defined and it isn't really clear when one or the other prefix should be used. As a result: if you are working alone (or your only teammate has very a mindset similar to yours), you won't need it, it will be just inconvenient. If you have a team of developers with various experiences and habits that need a convention to be enforced, it will be very hard to evaluate if they use prefixes correctly, let alone if commit messages are any good. The real problem is that commit messages and a changelog serve 2 different purposes and have different audiences. Changelog exists to explain what happened with the product, and commit messages exist to explain what happened with the code. These are the same thing only in the most basic situations, like "change Delete button color to red" (and then you probably don't even want to clutter your changelog with such bullshit at all). So, this works when 1 Jira ticket equals 1 commit. This is not usually the case, and, what's more, this usually shouldn't be the case. If your changelog audience is a project manager, for example, you are better off with generating if from ticket ids that you include into the commits that resolve some task (you don't need and probably don't want that atrocity of "conventional commits" for that). Changelog generated from "conventional commits" is verbose, clunky, sometimes outright false, misses most of important stuff if some things are resolved in libraries. It is simply bad. But arguably better than nothing if there are no tradeoffs. But there are. The real problem is, now your commits are bad as well, because they are completely fucked up in an attempt to shape them into a changelog, which cannot be done effectively. Best case scenario, your commits now completely mirror your tickets and you end up with huge commits, but at least the changelog looks OK-ish. So the tool intended for developers no more is. Anything in between and both your commits and your changelog are messed up.

lowercased 5y ago
> it will be very hard to evaluate if they use prefixes correctly, I faced this on a small team that adopted it. From my reading, it's OK if you create some of your own prefixes that suit your workflow. The point is to get everyone to use the same thing, not to try to say "feat/chore/etc" are the only things you can ever use. But... the team I was on didn't want to change anything, just use out of the box defaults, because "these are the community standards" (words to that effect). I do not like being forced in to the "conventional commit" style as it gives the impression that it's providing something of value, when, in our case, it's not really valuable to anyone on the team. I did some other work in 2019 on a different team which was much more efficient and effective with their commits, review, merging, etc, but didn't use conventional commit.
epage 5y ago
> I work with projects where this is utilized and I'm not sure they are better than nothing. At least you know which commits caused a breaking change compared to spelunking the history to figure out how a library broke compatibility and how you need to adapt to it. Breaking changes are honestly one of the main reasons I read changelogs. > The real problem is that commit messages and a changelog serve 2 different purposes and have different audiences. Changelog exists to explain what happened with the product, and commit messages exist to explain what happened with the code. imo a commit summary and the start of the body should explain the the goal, the user facing aspect and then should dig down into the whats and whys of how the changed lines support that goal, using Inverted Pyramid / Bottom-line Up Front writing style. Of course, if the commit has no end-user impact, you signify that with the type (feat/fix/etc vs chore/style/etc) While doing a hand-curated changelog for end-users would be more polished, the summary of a commit message should still be passable.
joshuanapoli 5y ago
Using pull-request descriptions for the auto-generated change-log helps give more flexibility for authors to describe their work. It's possible to embed media in the PR description. It' easier to encourage ample description in PR descriptions than commit messages. We often want to leave commits at a finer granularity than features, making it hard to leave a coherent story.

nivertech 5y ago

IMO it's a good idea to add a Github Issues label for each conventional commit type and scope: <type>[optional scope]: <description> fix: feat: build: chore: ci: docs: style: refactor: perf: test: etc. Let's say we have following scopes: core, infra, api, runtime. The add label in Github issues for each of them.

toastal 5y ago
Not a bad idea, but why would or should adding a label to a Git commit message have anything to do with GitHub?