slash dot dot dot

Evocative Commits

v0.0.2

Conventional Commits try to bridge the gap between commits (actual changes) and versioning (signalling changes).

This is a noble goal.

But they look kinda ugly.

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

feat!: send an email to the customer when a product is shipped

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

feat(api)!: send an email to the customer when a product is shipped

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

I think the comprehensibility of commit messages suggested by Drew DeVault is much too useful to be replaced and/or noised up by a bunch of special characters required by Conventional Commits.

Also, I would allege that it is much easier to generate a changelog, when git log is already as readable as a changelog should be.

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

Fix text rendering in CJK languages

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

Add support for protocol v3

commit deadbeefc0ffeeab0de1337dec0defacadef00d5
Author: John Doe
Date: 2000-01-01 00:00:00

Refactor CRTC handling

Furthermore, I fear that, if a commit author needs to follow certain syntactic rules, he might put too much of his focus and effort into following those rules instead of writing actually useful and intelligible commit messages.

bridging the gap

The gap between commits and versioning should be bridged.

But how? And at what cost?, are questions worth asking.

patterns

Even in natural language commit messages, we often reveal the nature of a change. Without any !: or feat uglyness.

If I write my commit messages disciplinedly, with the intention of communicating the significance of the change to people reading the commit, I am certain that in more than 99% of cases, people will be able to discern whether it constitutes a major, minor or patch version bump.

An approach similar to GitLab Issue Closing Patterns might be good enough, while keeping readability.

concluding

I suggest that if a commit message (including the commit body) contains any of the following words (case-insensitive), it may be considered a FEATURE change (minor version bump):

Or the following words for a BREAK change (major version bump):

Note: Patch version bumps need no such words. Changes that are not a BREAK or FEATURE always bump the patch version.

Note: Multiple changes of the same nature may only bump once.

Note: The word list is just a suggestion. You might want to add and remove words to tailor the list to your codebase and commit habits.

automation

Whether or not your authors are disciplined enough to allow for automation of versioning without review must be decided on a case-by-case basis.

Even without full automation, warning an author when tooling determines that a version is inappropriate for a change is useful.

If full automation is desired, I recommend only using it for FEATURE changes, never BREAK changes.

reserving !

This is a minor point, but maybe ! in commit messages should remain reserved for auto squash actions e.g. fixup!, squash!.

Arguably though, the "WORD! " syntax (space suffix) might not conflict with the "WORD!: " (colon suffix) syntax of Conventional Commits.

reiterating disciplined git workflow

Since I consider a disciplined git workflow rather useful, I want to reiterate some points of Drew DeVault's post:

related