[skrebbel]

On come on, this entire "spec" can be summarized in two sentences. It can be validated with a 13 character regex.

I share some of your sentiment though: I feel like the biggest reason to enforce a style like this is not for "machine readable commit messages" (I mean, why?), but to encourage people to split refactors and features in separate commits. This makes it easier to understand what's going on later.

I think this site should've begun with that, and left the spec as a footnote.

[antihero]

It's handy for auto bumping versions, too. If you have "feat" commits you know to bump minor, "fix" to bump patch, and "BREAKING" to bump major.

We use this in our lerna monorepo and it works like a charm as the CI can just bump whatever packages based on the paths and commit messages.

[wincent]

> Why?

The machine-readable part is useful for generating changelogs (eg. broken out by type) or implementing semver (eg. detecting breaking changes).

[hakre]

but isn't it an antipattern to generate change-logs from commit subject lines?

[wincent]

That all depends on what you do with the meta-data in the commits. For example, at my work, we analyze the history at the level of merges, not commits, and that works pretty well for us.

[cyphar]

Merge information is incredibly useful to developers (even if only to provide a smart "git bisect"). But would you generate a user-visible changelog from your merges? I personally wouldn't, and that's the point GP was making.

[wincent]

> But would you generate a user-visible changelog from your merges?

We can, and do. Knowing that the merges are going to wind up as items in the changelog leads us to size and structure them accordingly, or at least make a best effort to. The end result is a changelog where most PRs are somehow "noteworthy" and the ones that aren't (usually "chore" type in Conventional Commits lingo) can all be grouped together down the tail end.

The point isn't to produce a perfect result, but one that is "good enough". With this system, the friction to produce a new release is so low, and we have so many projects, that we can easily push out a steady stream of releases at very low cost with this approach. And following the pattern across all the projects has been great for consistency, compared to the relative chaos in patterns and procedures that we had before.

[wincent]

That all depends on what you do with the meta-data in the commits. For example, in my work, we analyze the history at the level of merges, not commits, and that works pretty well for us.

[ratherbefuddled]

Of course not. How else would you do it?

[cyphar]

Have a dedicated changelog you maintain[1].

Patch descriptions are for developers, not for users -- aside from the fact they're the wrong granularity (no user cares if it took 20 patches and three PR cycles to implement a feature), they should contain details and justification that are only useful for future debugging or for review purposes (which users also don't care about). And if you have a bugfix for a previously-merged patch that hasn't yet been released, why would you include the bugfix in the changelog?

Yes, with the right format and discipline you could generate reasonable changelogs from your commit logs -- but at that point it's so much easier to just keep a CHANGELOG.md.

[1]: https://keepachangelog.com/en/1.0.0/

[ratherbefuddled]

In my experience its unlikely this will be complete or accurate on any project maintained by a team of more than a couple of people.

Common practice for a long time has been to include a ticket id in the commit and then use a script to pull all the ticket ids from the commits since the last release and pull the (user facing) release note info from ticketing system.

Of course you don't want commit messages going to users but you don't want to rely on handcrafted lists either. Particularly when a release as far as a customer is concerned is infrequent and contains changes from many repos.

[dchest]

Make a human read the commit history (or tickets) and summarize changes in the language useful for users, not for developers.

[Vinnl]

Exactly. I can read commit messages myself, but there's a lot of stuff in there that's not relevant to me as a consumer - e.g. refactorings, cleanups, etc.

[adrianN]

I'm sure the human appreciates some help from a script that can parse metadata in the commit messages.

[Pfhreak]

You ever play or work on a game? Changelogs are a big deal over there. Automatically collecting them would be highly valuable.

[dgellow]

Do this from your JIRA (or equivalent) tickets then, you already have user oriented descriptions there. you can easily collect all tasks and bug tickets done during a sprint and generate a changelog. Though in practice I would expect someone to cleanup by hand.

[ratherbefuddled]

How do you link the tickets to the code that was actually built to be sure the changelog is complete and accurate?

It's usual to include the ticket id in the commit or PR so you can pull it from logs at build time and have a canonical list. Then grab the info to include from the ticketing system.

[_qwfv]

Ha! Maybe I just worked in a less organized game studio, but the only reliable record was the commit log.

Except when people would literally just mash their keyboard like this:

Commit 1234: iuadiuasdbuidawbiywbuqbqbdfpbdpiube