5 ms·

A specification for adding human and machine readable meaning to commit messages

42 points by nikolasavic 4y ago

nikolasavic 4y ago
I thought this was interesting, anyone using this? Is the juice worth the squeeze? Full title: Conventional Commits A specification for adding human and machine readable meaning to commit messages
- shagie 4y ago
  I do. I've got a plugin to help with remembering to do it and formatting - https://plugins.jetbrains.com/plugin/13389-conventional-commit https://plugins.jetbrains.com/plugin/13389-conventional-comm... The thing that it really helps doing (when you're using it) is avoiding doing multiple things in one commit. Features and refactors and fixes belong in different commits. With this I can also look at my git log and quickly see on the places where I changed things (rather than style or refactor or docs or tests). This commit, with a few lines did this - not "this change was part of this much bigger commit."
  - meling 4y ago
    Thanks for this tip about the plugin; I went looking and there is also an extension for vscode: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits https://marketplace.visualstudio.com/items?itemName=vivaxy.v... Haven't tried it but I will.
- manyxcxi 4y ago
  I follow it pretty closely. I don’t have any automation setup for changelogs or anything at this point, but it’s pretty easy for me, as back in ye old SVN/Trac days there were similar FIX, etc. semantics. I often have trouble with enough room to have a meaningful subject but the time I include commit scope and Jira ticket number, but I don’t mind, I normally use the body anyway.
- andrew_ 4y ago
  many popular javascript open source projects leverage this; webpack, vite, etc. It's very compatible with semver. all of my personal repos use it and any professional repos I have a say in use it.
- curun1r 4y ago
  I’ve found it’s too error prone to rely on developers remembering to use conventional commits. But when you use something like cocogitto [0], it makes writing compliant commit messages the path of least resistance. I’ve always liked the idea of conventional commits, but it never felt valuable in practice until I discovered the tooling to make it easy. [0] https://github.com/cocogitto/cocogitto https://github.com/cocogitto/cocogitto
- morgante 4y ago
  I used it extensively on https://github.com/terraform-google-modules https://github.com/terraform-google-modules. Maintaining up-to-date release notes on 50+ repos would be extremely time-consuming and error-prone without conventional commits.
rektide 4y ago
A coworker started a personal project & has- at least after a day or so of wild hacking- nice clean commits pretty close to this. I havent yet asked or found out what they're doing but looks great. Recently I'be started using "subsystem: change" type. Knowing the area seems like the most important starting queue.
markrages 4y ago
The examples given are more "what" changed than "why" it was changed. These are low-value commit messages because they are redundant with the content of the commit itself. It is almost like signing all your commits with your name or the current date. (Yes, I had a coworker who did this.) Better commit messages tell you what the situation was around the commit: Ticket number, or who wanted the change, or any other context that might tell you why the code was changed the way it was. Consider the dev accessing your commit through "blame". What does that user need to hear? Not which file or subsystem was changed. But the reason there is a change in the first place. My habit has been to prepare longer commit messages, a paragraph or two of explanatory text for that future developer, who is most likely future me. Policy at my company now squashes all my carefully-prepared commit messages into the one-liner "Merged $BRANCHNAME into main". I will probably just switch to the three character commit message "WIP" like my coworkers have done.
- andrew_ 4y ago
  all of that sounds awful, I'm sorry for your experiences. many repos are successfully using conventional commits in a way that's not low value, clear and concise in message, and useful in blame and walking history.
- jahsome 4y ago
  I've hit a couple shops in a row now where squashes are The Way. It's such a short-sighted and misguided policy. I don't understand what is so appealing about a linear commit history. It's a fabrication of reality, and I have never been grateful for it, only enraged. Why wouldn't you want to know what _actually_ happened? What is being gained besides an aesthetically pleasing "commits" tab on GitHub?
  - vbezhenar 4y ago
    Linear history is the only sane way to have usable history. Merge spaghetti is a good way to ensure that nobody would ever being able to navigate it. Squashing large number of commits is questionable practice, though.
ivan_gammel 4y ago
There’s a common convention that starts commit message with ticket numbers. Why tickets are not mentioned in the spec? This context is more important. Regarding choice of types: why „feature“ is shortened to „feat“? If there’s a type for feature, why another type is „fix“, not a „bug“? Semantically naming should be consistent. Automatic relationship with semver is questionable. Fix can be a change in architecture that deserves major version. Implementation of non-functional requirements is not a fix, yet it does not introduce new features and thus not a minor version increment. These are just two examples where inferred version is not what it could be. Making possible explicit expression of intent would help, e.g. by adding some tag like [minor]. Example: „APP-143:fix:major - migrated from mongodb to postgres“ „123456:new:patch — added logging of requests“
- shoo 4y ago
  I completely agree that linking to additional supporting docs that explain requirements, design, etc is very helpful. Especially for the crew of poor bloody maintenance contractors trying to reverse engineer the system requirements and constraints from the commit history a decade or two into the future, after everyone else originally involved with hauling the system into production has escaped/retired/died/fled changing their names and CVs. I've had some coworkers argue that the first line of the commit ("subject line" in git) is very important real estate, not to be wasted on a ticket reference, where it could instead hold a human readable summary. There's some merit to that. But they'd still include a reference to the ticket inside the body of the commit. Depending on how excitable one's org is about creating and migrating between issue trackers, sometimes a ticket reference can still be very ambiguous. I've seen one enterprise project migrate between different JIRA instances within the space of a couple of years, where depending on which instance you plugged the same ticket reference into, you'd get a completely different ticket!
  - regularfry 4y ago
    Jira integration is one place I've seen some real horrors - feature gets marked as "done" with a link to a git hash, then that patch gets bundled into a massive squash merge with a "changelog" that just says " merge 1/8/2022" and the feature branch deleted so the git hash gets lost. No traceability whatsoever.
dang 4y ago
Related: Conventional Commits - https://news.ycombinator.com/item?id=30950377 https://news.ycombinator.com/item?id=30950377 - April 2022 (1 comment) Conventional Commits - https://news.ycombinator.com/item?id=24208815 https://news.ycombinator.com/item?id=24208815 - Aug 2020 (23 comments) Conventional Commits: A specification for structured commit messages - https://news.ycombinator.com/item?id=21125669 https://news.ycombinator.com/item?id=21125669 - Oct 2019 (95 comments)
kkoncevicius 4y ago
Interesting, I am using a similar convention, but for GitHub issue labels, not commit messages [1]. Then, the commit messages often just refer to the issue number as a reference. [1]: http://karolis.koncevicius.lt/posts/improving_github_issue_labels/ http://karolis.koncevicius.lt/posts/improving_github_issue_l...
- nicolaslem 4y ago
  > the commit messages often just refer to the issue number as a reference. Please do not skip writing a meaningful commit message (explaining the why) because an issue number is referenced. At a previous job all commits referenced issue numbers of a dead issue tracker no one had access to anymore, rendering git blame useless.
d--b 4y ago
Giant sigh… The reason why commit messages are free form is so they can remain free form. It’s hard enough to make a model of the world in code. Why in hell would you want to impose this on commit messages?

42 points by nikolasavic 4y ago

I thought this was interesting, anyone using this? Is the juice worth the squeeze? Full title: Conventional Commits A specification for adding human and machine readable meaning to commit messages

shagie 4y ago
I do. I've got a plugin to help with remembering to do it and formatting - https://plugins.jetbrains.com/plugin/13389-conventional-commit https://plugins.jetbrains.com/plugin/13389-conventional-comm... The thing that it really helps doing (when you're using it) is avoiding doing multiple things in one commit. Features and refactors and fixes belong in different commits. With this I can also look at my git log and quickly see on the places where I changed things (rather than style or refactor or docs or tests). This commit, with a few lines did this - not "this change was part of this much bigger commit."
- meling 4y ago
  Thanks for this tip about the plugin; I went looking and there is also an extension for vscode: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits https://marketplace.visualstudio.com/items?itemName=vivaxy.v... Haven't tried it but I will.
manyxcxi 4y ago
I follow it pretty closely. I don’t have any automation setup for changelogs or anything at this point, but it’s pretty easy for me, as back in ye old SVN/Trac days there were similar FIX, etc. semantics. I often have trouble with enough room to have a meaningful subject but the time I include commit scope and Jira ticket number, but I don’t mind, I normally use the body anyway.
andrew_ 4y ago
many popular javascript open source projects leverage this; webpack, vite, etc. It's very compatible with semver. all of my personal repos use it and any professional repos I have a say in use it.
curun1r 4y ago
I’ve found it’s too error prone to rely on developers remembering to use conventional commits. But when you use something like cocogitto [0], it makes writing compliant commit messages the path of least resistance. I’ve always liked the idea of conventional commits, but it never felt valuable in practice until I discovered the tooling to make it easy. [0] https://github.com/cocogitto/cocogitto https://github.com/cocogitto/cocogitto
morgante 4y ago
I used it extensively on https://github.com/terraform-google-modules https://github.com/terraform-google-modules. Maintaining up-to-date release notes on 50+ repos would be extremely time-consuming and error-prone without conventional commits.

rektide 4y ago

A coworker started a personal project & has- at least after a day or so of wild hacking- nice clean commits pretty close to this. I havent yet asked or found out what they're doing but looks great. Recently I'be started using "subsystem: change" type. Knowing the area seems like the most important starting queue.

markrages 4y ago

The examples given are more "what" changed than "why" it was changed. These are low-value commit messages because they are redundant with the content of the commit itself. It is almost like signing all your commits with your name or the current date. (Yes, I had a coworker who did this.) Better commit messages tell you what the situation was around the commit: Ticket number, or who wanted the change, or any other context that might tell you why the code was changed the way it was. Consider the dev accessing your commit through "blame". What does that user need to hear? Not which file or subsystem was changed. But the reason there is a change in the first place. My habit has been to prepare longer commit messages, a paragraph or two of explanatory text for that future developer, who is most likely future me. Policy at my company now squashes all my carefully-prepared commit messages into the one-liner "Merged $BRANCHNAME into main". I will probably just switch to the three character commit message "WIP" like my coworkers have done.

andrew_ 4y ago
all of that sounds awful, I'm sorry for your experiences. many repos are successfully using conventional commits in a way that's not low value, clear and concise in message, and useful in blame and walking history.
jahsome 4y ago
I've hit a couple shops in a row now where squashes are The Way. It's such a short-sighted and misguided policy. I don't understand what is so appealing about a linear commit history. It's a fabrication of reality, and I have never been grateful for it, only enraged. Why wouldn't you want to know what _actually_ happened? What is being gained besides an aesthetically pleasing "commits" tab on GitHub?
- vbezhenar 4y ago
  Linear history is the only sane way to have usable history. Merge spaghetti is a good way to ensure that nobody would ever being able to navigate it. Squashing large number of commits is questionable practice, though.

ivan_gammel 4y ago

There’s a common convention that starts commit message with ticket numbers. Why tickets are not mentioned in the spec? This context is more important. Regarding choice of types: why „feature“ is shortened to „feat“? If there’s a type for feature, why another type is „fix“, not a „bug“? Semantically naming should be consistent. Automatic relationship with semver is questionable. Fix can be a change in architecture that deserves major version. Implementation of non-functional requirements is not a fix, yet it does not introduce new features and thus not a minor version increment. These are just two examples where inferred version is not what it could be. Making possible explicit expression of intent would help, e.g. by adding some tag like [minor]. Example: „APP-143:fix:major - migrated from mongodb to postgres“ „123456:new:patch — added logging of requests“

shoo 4y ago
I completely agree that linking to additional supporting docs that explain requirements, design, etc is very helpful. Especially for the crew of poor bloody maintenance contractors trying to reverse engineer the system requirements and constraints from the commit history a decade or two into the future, after everyone else originally involved with hauling the system into production has escaped/retired/died/fled changing their names and CVs. I've had some coworkers argue that the first line of the commit ("subject line" in git) is very important real estate, not to be wasted on a ticket reference, where it could instead hold a human readable summary. There's some merit to that. But they'd still include a reference to the ticket inside the body of the commit. Depending on how excitable one's org is about creating and migrating between issue trackers, sometimes a ticket reference can still be very ambiguous. I've seen one enterprise project migrate between different JIRA instances within the space of a couple of years, where depending on which instance you plugged the same ticket reference into, you'd get a completely different ticket!
- regularfry 4y ago
  Jira integration is one place I've seen some real horrors - feature gets marked as "done" with a link to a git hash, then that patch gets bundled into a massive squash merge with a "changelog" that just says " merge 1/8/2022" and the feature branch deleted so the git hash gets lost. No traceability whatsoever.

dang 4y ago

Related: Conventional Commits - https://news.ycombinator.com/item?id=30950377 https://news.ycombinator.com/item?id=30950377 - April 2022 (1 comment) Conventional Commits - https://news.ycombinator.com/item?id=24208815 https://news.ycombinator.com/item?id=24208815 - Aug 2020 (23 comments) Conventional Commits: A specification for structured commit messages - https://news.ycombinator.com/item?id=21125669 https://news.ycombinator.com/item?id=21125669 - Oct 2019 (95 comments)

kkoncevicius 4y ago

Interesting, I am using a similar convention, but for GitHub issue labels, not commit messages [1]. Then, the commit messages often just refer to the issue number as a reference. [1]: http://karolis.koncevicius.lt/posts/improving_github_issue_labels/ http://karolis.koncevicius.lt/posts/improving_github_issue_l...

nicolaslem 4y ago
> the commit messages often just refer to the issue number as a reference. Please do not skip writing a meaningful commit message (explaining the why) because an issue number is referenced. At a previous job all commits referenced issue numbers of a dead issue tracker no one had access to anymore, rendering git blame useless.

d--b 4y ago

Giant sigh… The reason why commit messages are free form is so they can remain free form. It’s hard enough to make a model of the world in code. Why in hell would you want to impose this on commit messages?