5 ms·

Conventional Commits

37 points by smartmic 6y ago

hirundo 6y ago
> Example: Commit message with both ! and BREAKING CHANGE footer: > refactor!: drop support for Node 6 From Wikipedia's Code Refactoring: > In computer programming and software design, code refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior. So if a code change is just a refactor, then its external behavior is unchanged, therefore it is not a breaking change. These two commit labels are incompatible.
- sonofgod 6y ago
  Once the decision has been made that Node 6 is no longer supported, it is then possible to refactor the code so that it uses appropriate modern idioms, such that the external behaviour is unchanged for Node 6+ but will no longer be parsable by Node 5. In this specific case, it is both a refactor and a breaking change.
- jschpp 6y ago
  I think they use the angular definition which doesn't explicit forbid this > refactor: A code change that neither fixes a bug nor adds a feature But yeah I'm with you in saying that this particular example is not well choosen
thephyber 6y ago
The most interesting things about Conventional Commits are that they can be deterministically digested by a process to decide how to bump a SemVer and similarly to create a formatted CHANGELOG file.
- dzuc 6y ago
  ^ https://github.com/semantic-release/semantic-release https://github.com/semantic-release/semantic-release
- oppodeldoc 6y ago
  Yeah, https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version is a really great tool for this, we use it and the versioning is relatively seamless for releases.
- runarberg 6y ago
  I really wished we had type systems good enough, and tools smart enough to figure the semver bump by it self. Ideally humans should not come near semver bumping, not even through the commit messages.
  - yawaramin 6y ago
    Elm does have a type-directed version bump tool. Is that what you were thinking of?
OpossumMinister 6y ago
After working on a project that had code commit linters like this, that block you from committing if there's a violation, it's absolutely awful. You cannot work incrementally at all since "inject logger" is not a feature. Since most people aren't comfortable with rebasing (i don't know why), you end up with a ton of nonsense like a whole chain of refactors or feats that aren't actual refactors or features, they're just there to appease the tool since you can't commit (even locally!) without them. Just stick to squash-before-merge-to-master, thanks.
- wffurr 6y ago
  Squash merge and commit linter only on master seems like the way to go here. Then you can do whatever you want in your feature branch, and then when the feature is ready, create the squashed commit with the proper commit formatting.
  - ArchOversight 6y ago
    squash merges to master are terrible for those that want to go looking why a certain change was introduced. Now a larger change set is hidden behind a squash merge, and why was line 50 in foobar.py updated? Who knows, it was part of this giant merge request which no longer provides context why the developer changed line 50 in foobar.py. Commit messages should explain why the change was made to the code. The amount of times that I go diving into a codebase only to find that the change was introduced in a larger commit that just says "fix bug" with no further information is maddening.
    - jasonpeacock 6y ago
      You're describing the wrong use of squash merges, and I agree they suck. The right use is to allow me to make crappy, random commits on my own feature branch, clean them up those commits when I'm ready to release the change. And the commit description will describe what's going on. The key is that my feature branch is not long-lived - only a day or two, long enough for me to make a step forward before merging it back into mainline and then starting on the next step.
BenjaminCoe 6y ago
Hey, I'm the original co-author of the "Conventional Commits" spec. Although, I should give credit where credit is due, and say that it evolves directly from Angular commit conventions. I started adopting these conventions with the goal of automating releases, both on my open-source and on the services I was working on at npm (I've since brought the practice to my team at Google). I very much did not want to introduce road blocks to folks committing to their own branches -- which is what the "rewrite the message when you squash" advice grows from. Here's a post I wrote on how my team uses Conventional Commits in our release process: https://dev.to/bcoe/how-my-team-releases-libraries-23el https://dev.to/bcoe/how-my-team-releases-libraries-23el
yawaramin 6y ago
My take on this is that, all else being equal, it seems the major selling point of Conventional Commits is that their commit summaries can be used to calculate the next version bump. But IMHO, instead of asking everyone to annotate every single commit message with a marker just so a separate tool can process it (possibly to get it wrong), it's better to just update the version directly when making changes. This way the version bump is deliberately and carefully thought out, and doesn't need to pollute all commit messages in the process.

37 points by smartmic 6y ago

> Example: Commit message with both ! and BREAKING CHANGE footer: > refactor!: drop support for Node 6 From Wikipedia's Code Refactoring: > In computer programming and software design, code refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior. So if a code change is just a refactor, then its external behavior is unchanged, therefore it is not a breaking change. These two commit labels are incompatible.

sonofgod 6y ago
Once the decision has been made that Node 6 is no longer supported, it is then possible to refactor the code so that it uses appropriate modern idioms, such that the external behaviour is unchanged for Node 6+ but will no longer be parsable by Node 5. In this specific case, it is both a refactor and a breaking change.
jschpp 6y ago
I think they use the angular definition which doesn't explicit forbid this > refactor: A code change that neither fixes a bug nor adds a feature But yeah I'm with you in saying that this particular example is not well choosen

thephyber 6y ago

The most interesting things about Conventional Commits are that they can be deterministically digested by a process to decide how to bump a SemVer and similarly to create a formatted CHANGELOG file.

dzuc 6y ago
^ https://github.com/semantic-release/semantic-release https://github.com/semantic-release/semantic-release
oppodeldoc 6y ago
Yeah, https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version is a really great tool for this, we use it and the versioning is relatively seamless for releases.
runarberg 6y ago
I really wished we had type systems good enough, and tools smart enough to figure the semver bump by it self. Ideally humans should not come near semver bumping, not even through the commit messages.
- yawaramin 6y ago
  Elm does have a type-directed version bump tool. Is that what you were thinking of?

OpossumMinister 6y ago

After working on a project that had code commit linters like this, that block you from committing if there's a violation, it's absolutely awful. You cannot work incrementally at all since "inject logger" is not a feature. Since most people aren't comfortable with rebasing (i don't know why), you end up with a ton of nonsense like a whole chain of refactors or feats that aren't actual refactors or features, they're just there to appease the tool since you can't commit (even locally!) without them. Just stick to squash-before-merge-to-master, thanks.

wffurr 6y ago
Squash merge and commit linter only on master seems like the way to go here. Then you can do whatever you want in your feature branch, and then when the feature is ready, create the squashed commit with the proper commit formatting.
- ArchOversight 6y ago
  squash merges to master are terrible for those that want to go looking why a certain change was introduced. Now a larger change set is hidden behind a squash merge, and why was line 50 in foobar.py updated? Who knows, it was part of this giant merge request which no longer provides context why the developer changed line 50 in foobar.py. Commit messages should explain why the change was made to the code. The amount of times that I go diving into a codebase only to find that the change was introduced in a larger commit that just says "fix bug" with no further information is maddening.
  - jasonpeacock 6y ago
    You're describing the wrong use of squash merges, and I agree they suck. The right use is to allow me to make crappy, random commits on my own feature branch, clean them up those commits when I'm ready to release the change. And the commit description will describe what's going on. The key is that my feature branch is not long-lived - only a day or two, long enough for me to make a step forward before merging it back into mainline and then starting on the next step.

BenjaminCoe 6y ago

Hey, I'm the original co-author of the "Conventional Commits" spec. Although, I should give credit where credit is due, and say that it evolves directly from Angular commit conventions. I started adopting these conventions with the goal of automating releases, both on my open-source and on the services I was working on at npm (I've since brought the practice to my team at Google). I very much did not want to introduce road blocks to folks committing to their own branches -- which is what the "rewrite the message when you squash" advice grows from. Here's a post I wrote on how my team uses Conventional Commits in our release process: https://dev.to/bcoe/how-my-team-releases-libraries-23el https://dev.to/bcoe/how-my-team-releases-libraries-23el

yawaramin 6y ago

My take on this is that, all else being equal, it seems the major selling point of Conventional Commits is that their commit summaries can be used to calculate the next version bump. But IMHO, instead of asking everyone to annotate every single commit message with a marker just so a separate tool can process it (possibly to get it wrong), it's better to just update the version directly when making changes. This way the version bump is deliberately and carefully thought out, and doesn't need to pollute all commit messages in the process.