11 ms·

Conventional Commits: A specification for structured commit messages

157 points by BenjaminCoe 7y ago

wwqrd 7y ago
lost me at “feat”
- _asummers 7y ago
  I would rather shorten the standard tags around it than have to shorten the 80 char short commit message. Typically tooling allows you to add your own tags (e.g. imp: for improvement) so you could add feature, but I find myself needing those extra few characters more often than not
house9-2 7y ago
> feat: a commit of the type feat introduces a new feature to the codebase instead of 'feat:', why not 'feature:'? I dislike partial abbreviation because it is confusing; yes doc for document and max for maximum make sense but in this case feat is literally a different word?
- ChristianBundy 7y ago
  And while we're at it, why don't we just use full sentences? Before: > feat: allow provided config object to extend other configs After > Add option for config object to extend other configs I know this isn't the point of changelogs, but I've been using the verbs from KeepAChangelog to start my commit messages and it's been going well so far. > Add template preview to status page > Change textarea to increase height on `:focus` > Remove deprecated CLI flags > Fix margin styles causing layout problems
  - YorickPeterse 7y ago
    I agree that full sentences (e.g. like Email subjects or blog post titles) are better. Tagging commits with feature/bug/etc is not particularly useful, as more often than not the line between feature, bug, etc is blurry. At times it can also be unclear what tag to use, leading to arbitrary choices. For example: is a performance improvement a feature, or a bug fix? The tags also add no value when reading commit messages. Setting that aside, the conventional commit "standard" (https://xkcd.com/927/ https://xkcd.com/927/) doesn't focus on what I think is the most important aspect of a commit: a good commit subject and message. In fact, prefixing the subject line with certain tags limits the amount of characters you have for writing the message; assuming you want to stick with the usual 50 character limit.
    - JMTQp8lwXL 7y ago
      > feature/bug/etc is not particularly useful It's useful for automatically determining the next semantic release version by inspecting the commit history alone. fix: <-- patch feat: <-- minor breaking: <-- major
      - munk-a 7y ago
        That seems inaccurate, it looks more like fix: feat: are both potentially patch level while fix!: feat!: breaking change: and breaking change!: indicate major changes... possibly? Ouf I think the commit is just absolutely the wrong level to encode this at - I much prefer ticket level encoding of this information.
        JMTQp8lwXL 7y ago
        I was explaining how standard-version [0] works. Conventional Commits homepage doesn't mention anything about the '!' syntax. [1] I'm unsure if you're suggesting that's how you think it should work, or how it actually works. I haven't ever tried using the '!' syntax, so I can't say for certain. In terms of release management, it makes configuring CI jobs simpler with one less parameter. If you automatically release merges to master, you can use standard-version with conventional commit syntax. On other projects, I've seen people use GitHub PR labels to mark 'major', 'minor', or 'patch' releases (the CI system reads this information when generating releases). If you feel it's inappropriate for this information to live in your commit history, you'll need to specify it through one of these other options. Since I don't have a dedicated team for this sort of infrastructure (I maintain my own Jenkins jobs), I find that Conventional Commits get the job done, so I can focus on other things. There could be better ways, but I have more pressing problems than demand my attention, with higher priority than optimizing my CICD configurations. [0]: https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version [1]: https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
        arethuza 7y ago
  - greggman2 7y ago
    Why? Why is there such a strong desire for full sentences? It's pedantic to me. I'm completly fine with terse incomplete sentences. They are not harder to understand. Plus I work with international teams. Terse is often easier to write and understand for non-native speakers.
    - nirvdrum 7y ago
      I worked on an international team with non-native speakers and we found proper casing and punctuation easier to read.
    - deleted 7y ago
      [deleted]
    - greggman2 7y ago
      OCD seems prevalent in programmers. For me full sentence comment / commit message requirements are the ultimate process for the sake of process. Such a bikeshedding waste of time. Such policies serve absolutely no objective purpose. They're only there to satisfy some leader's asthetic senses and feeling of control. As for easier to read thousands of newspaper headlines and magazine article titles provide strong evidence otherwise. Even HN itself is proof it doesn't matter
- nikolay 7y ago
  I also dislike unnecessary abbreviations. "Feat" saves you just 3 characters, but earns you ugliness and confusion.
  - spartanatreyu 7y ago
    It seems like it was made by someone who accidentally spilt coffee on their keyboard which made their 'U' key sticky. I like my "Feature" much more than "feat". This is my default commit message that I edit to contain what I want: <Type>: <Description> # Type can be: # - Feature: A new feature # - Bugfix: A bug fix # - Docs: Documentation only changes # - Styling: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) # - Refactor: A code change that neither fixes a bug nor adds a feature # - Performance: A code change that improves performance # - Tests: Adding missing tests # - Chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
    - nikolay 7y ago
      Nice! "Styling" could be ambiguous though. I personally use "Formatting" instead.
      - mdtusz 7y ago
        I typically go with "Linting". "Formatting" could mean something different in some contexts.
        nikolay 7y ago
        That's even a better choice. Thank you!
- inlined 7y ago
  Probably because tools like github truncate large titles
- sfink 7y ago
  Tha i wha I cam her t writ a wel. D w reall nee t repea th infamou Uni mistak wit th "creat" syscal? Thin o th childre!
- magicalhippo 7y ago
  Because it makes you feel good from sounding like you've just accomplished a feat when you commit the feature.
- JMTQp8lwXL 7y ago
  Commit messages should be short. If you're familiar with conventional commit syntax (and chances are, your team will tell you to follow it, if your repository follows it), then your mind will automatically expand 'feat' to 'feature'.
- munk-a 7y ago
  `feat` is only a saver over `feature` if you're making a descriptor that was optional into something required - I admit I've never worked with a public commit history but for our internal projects commit messages are expected to give some justification or explanation of the necessity of the change without any formatting specifically enforced (though we require branches to contain at least one commit that pulls in the related issue ticket #). I much prefer encoding structured information like this at the ticket level where history can be more easily corrected and items are expected to be visible for all of time.
- dvcrn 7y ago
  Titles of commit messages should be short and concise, any extra information can go into the body of the commit. A common guideline is to have the title capped at 50 characters. If you work on the CLI, having a concise git log is far easier to skim than having very long commit messages and if I want to know more about the commit, I will check the body. It's also what a lot of websites use to truncate the title. From my experience, a few characters less do matter (which is also why I dropped conventional commits and just use "Add blah blah to blah", "Fix typo in user-facing message").
- Svoka 7y ago
  And only saves you like 3 symbols. Made a pull request fixing it https://github.com/conventional-commits/conventionalcommits.org/pull/204 https://github.com/conventional-commits/conventionalcommits....
  - vemv 7y ago
    You're not saving them any work by creating that PR. That's better discussed and agreed on in advance.
mohaba 7y ago
feat of strength or great strength of feet?
- ledauphin 7y ago
  ...don't follow.
deleted 7y ago
[deleted]
rinchik 7y ago
Isn't wording a bit off? "scope" should describe what the commit DOES, not what you are personally DOING, and not what you were intended to DO. "body", optionally, describes WHY. Also it feels like more of a convention for a personal project with optional C(I|D) automation prerequisites. In a team there should be a clear and emphasized place for the issue tracking info (ticket number, task id etc etc)
- GordonS 7y ago
  I quite like the idea of `scope` for large, multi-component projects, so you can tell instantly from the commit message what component has been changed.
inlined 7y ago
SemVer is generally good practice but I don’t like promotion to religion. For example, during the pre-release of the firebase-functions SDK we shifted SemVer by one: 0.2.1 was a feature addition from 0.2.0 and a breaking change from 0.1. Similarly there are rare cases where I’ve swept breaking changes under the rug because they were severe bug or security fixes that affected a corner case unlikely to be seen in the wild.
- hyperpape 7y ago
  I believe the first one is semver: before 1.0, anything can change at any time. https://semver.org/ https://semver.org/
kazinator 7y ago
I'm sticking to the GNU ChangeLog format, thanks. https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs https://www.gnu.org/prep/standards/html_node/Change-Logs.htm... This widely used format gives details about what is being done to each function. This was designed to be used in a ChangeLog file, so it has to be adopted for repository use. We don't have to record the date and name, since that is in the commit meta-data. WE write a commit title, and then the ChangeLog entry becomes the details placed after the blank line. That entry is mandatory: no title-only commits! There can be one or more discussion paragraphs between the title and the ChangeLog entry. We know that these paragraphs aren't ChangeLog entry material because they don't begin with the asterisk. Like this: http://www.kylheku.com/cgit/txr/commit/?id=b2739251281d7f6ef4d30164101bdf2a8d537a72 http://www.kylheku.com/cgit/txr/commit/?id=b2739251281d7f6ef...
- epage 7y ago
  Personally, I feel like this style puts the focus on what rather than the why. I also dislike that it seems to be centered on multiple changes in one commit.
abtinf 7y ago
I’ve found the commit message guidelines at https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project https://git-scm.com/book/en/v2/Distributed-Git-Contributing-... to very helpful for clarity. “ The last thing to keep in mind is the commit message. Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation. The Git project requires that the more detailed explanation include your motivation for the change and contrast its implementation with previous behavior — this is a good guideline to follow. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug."”
- nirvdrum 7y ago
  50 chars seems pretty arbitrary to me. I'd rather have a useful commit message. I've seen some pretty contorted messages conveying no real info in order to meet an imaginary character limit.
  - hakre 7y ago
    the 50 chars is for the subject. the commit message (body) has no character limit (apart from a character limit per line).
    - hoseja 7y ago
      It's still overly restrictive and ossified from terminals / email subjects or whatever.
    - nirvdrum 7y ago
      Right. But that's the limit I don't get. If I always have to view the expanded set of commit messages to understand anything about the commit, what's the value in a short subject? And why 50 chars? That's even more restrictive than the normal 72/76/80 chars.
andrewprock 7y ago
This strikes me as quintessential bike shedding, process for the sake of process.
AndrewHampton 7y ago
We've been following conventional commits for our front end code for the last year or so at my work. In other repositories, we've loosely followed the keep a change log conventions. I find conventional commits great when your repository will produce a package to be consumed by others. For example, conventional commits for our shared JS code helps us produce great change logs and helps us easily follow semver for the NPM packages our other applications use. However, I don't find it that useful in the the final applications, even counter productive, since it typically will take up quite a bit of space in the commit title. Many of our front end devs completely ignore title length conventions now.
- jackcodes 7y ago
  Why don’t they put the additional information in the body of the commit? I see this in nearly every company I go to - everyone rushing to skip over adding anything useful to the permanent log by using git commit -m rather than a plain got commit.
  - _asummers 7y ago
    This is the place where (mentioned elsewhere in this thread) things like issue tracker links and other context can and _should_ go if you're using something like CC.
  - AndrewHampton 7y ago
    Oh, we do. We are generally pretty great at filling in good details in the body. I didn't mention that originally because I didn't think it was noteworthy. The main problem is very commit titles that end up looking like: feat(SomeScope.OtherScope.Class): add support for abc and xyz option
Aeolun 7y ago
I don’t think this is so much to make your commit messages better, as it is to make sure that all of them can be automatically processed into changelog and semver updates.
- _asummers 7y ago
  This is the way to think about it. It's concise enough and has tooling in enough languages to where generating the changelog from the commit messages is just a CI step, but it doesn't offer much more. I like and have used Conventional Commits for several years, but the goal is just tooling around telling others what changed outside of reading the git log, e.g. PMs who want an HTML artifact.
notmyfuture 7y ago
For use cases where this level of rigour is desired, it would be nice to have real separate metadata vs. convention. Doing this by convention is unreliable.
- wincent 7y ago
  You can get a basic level of enforcement for free by turning on the "Semantic Pull Requests" bot that will let you know when you forget the type (or use an invalid one): https://github.com/probot/semantic-pull-requests https://github.com/probot/semantic-pull-requests It obviously won't catch your mistake if you forget to mark a breaking change as breaking, but it's a start.
epage 7y ago
At $DAYJOB, we organically switched from not having any formal style to having an internal formal style. People seemed to want the benefits of tooling integration and clearer communication. Right now, we are switching SCM's and are looking at adopting Conventional to replace our internal style. I've already started using Conventional and have really appreciated it. It makes it fast and succinct (remember, line length "requirements" in git) to get the information you need even in one-line logs. Also, it makes CHANGELOG maintenance easier, whether using an automated tool or doing it by-hand. Not happy with the other ones, I've created my own commit style validation tool, committed [0] and have deployed it on my open source projects. Like code style enforcement in CI, I like delegating this to a tool since it makes the requirement very clear for contributors. The one thing I'm disappointed with with Conventional is that they did not follow git conventions for multi-line trailers. [0] https://github.com/crate-ci/committed https://github.com/crate-ci/committed
- mgoblu3 7y ago
  Similar experience here. On really big teams sure, you can bike shed the format a ton, but they’re all relatively close enough but CC has some good tooling so we just ran with it. Results have been fine, didn’t waste a bunch of time debating it. Haven’t figured out a good way to integrate co-authors easily with it though.
  - epage 7y ago
    Wouldn't Co-Authors just be a footer/trailer?
eyegor 7y ago
> When you used a type not of the spec, e.g. feet instead of feat This actually had me laughing quite a bit. Because of my love for dad jokes, here are some less conventional commits: "fete" : adding holiday support "braking change" : a change of pace "nix" : removing a featute "suffix" : adding a nice to have
zoomablemind 7y ago
Commit messages are just that - an additional communication tool. As long as any format helps keep the understanding within a team clear with a minimum of overhead, so be it. After all the commit message is secondary to the actual code committed. I'm sure everyone can share an episode when a nicely worded commit had to be followed up with an ugly 'Fix a typo' message. The most practical convention is the one that's automated to some degree, for example, issue/feature tag auto-linking or some template driven messages. Either way the message should not become an ultimate hoop to jump before the actual commit and one more thing to 'maintain', the code should be the focus. In my experience, a commit message describing the committed behavior (even when intended) helps tie the code to the overall scope. In case when it's a bugfix, it still must be tied to a correct expected behavior. So in some sense a commit message could serve as an auxilliary level of unit testing. Of course, I'd rather put an effort to enforce the actual practice of unit testing over structuring the commit messages.
- pantalaimon 7y ago
  > I'm sure everyone can share an episode when a nicely worded commit had to be followed up with an ugly 'Fix a typo' message. There is `git commit --fixup` and `git rebase -i --autosquash` for that ;)
jevgeni 7y ago
Imagine the following future: “Have you linted and unit tested your commit message?” “Junior Developer wanted. 10 years of Conventional Commits experience required.” “Download Conventionalizer! Now you can write Conventional Commits in plain English, having all the syntax automatically generated! (node, erlang OTP and Jerry’s pre-alpha TensorFlow binding library required. Windows support coming soon.)” Something tells me the authors are hard at work solving a problem nobody needs solving.
- skrebbel 7y ago
  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.
  - wincent 7y ago
    > Why? The machine-readable part is useful for generating changelogs (eg. broken out by type) or implementing semver (eg. detecting breaking changes).
    - hakre 7y ago
      but isn't it an antipattern to generate change-logs from commit subject lines?
      - ratherbefuddled 7y ago
        Of course not. How else would you do it?
        dchest 7y ago
        Make a human read the commit history (or tickets) and summarize changes in the language useful for users, not for developers.
boring_twenties 7y ago
This would be better if it was called the Committer Convenant.
t0astbread 7y ago
I do something like this but for branch names. This spec recommends a squash-merge workflow to turn branches into commits before merge. Why would I wanna do that? It seems like throwing away a lot of detail unnecessarily.
vemv 7y ago
prefixes such as "fix: " are better expressed at the bottom of the commit message body. They are metadata, and as such they shouldn't take more attention than the actual data. This matters when you are in a bug hunt in production - you want to find the culprit commit as efficiently as possible, without distractions.
dajohnson89 7y ago
maybe it's just me, but things like this sap half the fun out of development.
Karupan 7y ago
We’ve found conventional commits useful in our mono repo. Instead of letting the authors deal with versioning (which sometimes breaks dependencies), our build pipeline determines the semver from the commit messages. This has made it easier to deal with releases for around two dozen packages by developers spread across three different countries.
w_t_payne 7y ago
I have a system that creates commit messages automatically. The commit messages themselves are YAML so that they can contain various bits of metadata - current task id, timestamps for oldest/newest known builds associated with that task etc...
crististm 7y ago
I like best the irony of "refactor!". A breaking change with a title meaning there should not be semantic changes in the code...
sime2009 7y ago
I have to admit that in the GitHub and PR era I rarely look at individual commits or their messages. I look at whole PRs.
leerob 7y ago
Conventional commits pair nicely with a Lerna monorepo when deploying multiple JS packages at once. Auto-generated changelogs and automatic semver for packages. It's worked well for us over the past year. https://github.com/lerna/lerna/blob/master/commands/version/README.md#--conventional-commits https://github.com/lerna/lerna/blob/master/commands/version/...

157 points by BenjaminCoe 7y ago

wwqrd 7y ago

lost me at “feat”

_asummers 7y ago
I would rather shorten the standard tags around it than have to shorten the 80 char short commit message. Typically tooling allows you to add your own tags (e.g. imp: for improvement) so you could add feature, but I find myself needing those extra few characters more often than not

house9-2 7y ago

> feat: a commit of the type feat introduces a new feature to the codebase instead of 'feat:', why not 'feature:'? I dislike partial abbreviation because it is confusing; yes doc for document and max for maximum make sense but in this case feat is literally a different word?

ChristianBundy 7y ago
And while we're at it, why don't we just use full sentences? Before: > feat: allow provided config object to extend other configs After > Add option for config object to extend other configs I know this isn't the point of changelogs, but I've been using the verbs from KeepAChangelog to start my commit messages and it's been going well so far. > Add template preview to status page > Change textarea to increase height on `:focus` > Remove deprecated CLI flags > Fix margin styles causing layout problems
- YorickPeterse 7y ago
  I agree that full sentences (e.g. like Email subjects or blog post titles) are better. Tagging commits with feature/bug/etc is not particularly useful, as more often than not the line between feature, bug, etc is blurry. At times it can also be unclear what tag to use, leading to arbitrary choices. For example: is a performance improvement a feature, or a bug fix? The tags also add no value when reading commit messages. Setting that aside, the conventional commit "standard" (https://xkcd.com/927/ https://xkcd.com/927/) doesn't focus on what I think is the most important aspect of a commit: a good commit subject and message. In fact, prefixing the subject line with certain tags limits the amount of characters you have for writing the message; assuming you want to stick with the usual 50 character limit.
  - JMTQp8lwXL 7y ago
    > feature/bug/etc is not particularly useful It's useful for automatically determining the next semantic release version by inspecting the commit history alone. fix: <-- patch feat: <-- minor breaking: <-- major
    - munk-a 7y ago
      That seems inaccurate, it looks more like fix: feat: are both potentially patch level while fix!: feat!: breaking change: and breaking change!: indicate major changes... possibly? Ouf I think the commit is just absolutely the wrong level to encode this at - I much prefer ticket level encoding of this information.
      - JMTQp8lwXL 7y ago
        I was explaining how standard-version [0] works. Conventional Commits homepage doesn't mention anything about the '!' syntax. [1] I'm unsure if you're suggesting that's how you think it should work, or how it actually works. I haven't ever tried using the '!' syntax, so I can't say for certain. In terms of release management, it makes configuring CI jobs simpler with one less parameter. If you automatically release merges to master, you can use standard-version with conventional commit syntax. On other projects, I've seen people use GitHub PR labels to mark 'major', 'minor', or 'patch' releases (the CI system reads this information when generating releases). If you feel it's inappropriate for this information to live in your commit history, you'll need to specify it through one of these other options. Since I don't have a dedicated team for this sort of infrastructure (I maintain my own Jenkins jobs), I find that Conventional Commits get the job done, so I can focus on other things. There could be better ways, but I have more pressing problems than demand my attention, with higher priority than optimizing my CICD configurations. [0]: https://github.com/conventional-changelog/standard-version https://github.com/conventional-changelog/standard-version [1]: https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
        arethuza 7y ago
- greggman2 7y ago
  Why? Why is there such a strong desire for full sentences? It's pedantic to me. I'm completly fine with terse incomplete sentences. They are not harder to understand. Plus I work with international teams. Terse is often easier to write and understand for non-native speakers.
  - nirvdrum 7y ago
    I worked on an international team with non-native speakers and we found proper casing and punctuation easier to read.
  - deleted 7y ago
    [deleted]
  - greggman2 7y ago
    OCD seems prevalent in programmers. For me full sentence comment / commit message requirements are the ultimate process for the sake of process. Such a bikeshedding waste of time. Such policies serve absolutely no objective purpose. They're only there to satisfy some leader's asthetic senses and feeling of control. As for easier to read thousands of newspaper headlines and magazine article titles provide strong evidence otherwise. Even HN itself is proof it doesn't matter
nikolay 7y ago
I also dislike unnecessary abbreviations. "Feat" saves you just 3 characters, but earns you ugliness and confusion.
- spartanatreyu 7y ago
  It seems like it was made by someone who accidentally spilt coffee on their keyboard which made their 'U' key sticky. I like my "Feature" much more than "feat". This is my default commit message that I edit to contain what I want: <Type>: <Description> # Type can be: # - Feature: A new feature # - Bugfix: A bug fix # - Docs: Documentation only changes # - Styling: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) # - Refactor: A code change that neither fixes a bug nor adds a feature # - Performance: A code change that improves performance # - Tests: Adding missing tests # - Chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
  - nikolay 7y ago
    Nice! "Styling" could be ambiguous though. I personally use "Formatting" instead.
    - mdtusz 7y ago
      I typically go with "Linting". "Formatting" could mean something different in some contexts.
      - nikolay 7y ago
        That's even a better choice. Thank you!
inlined 7y ago
Probably because tools like github truncate large titles
sfink 7y ago
Tha i wha I cam her t writ a wel. D w reall nee t repea th infamou Uni mistak wit th "creat" syscal? Thin o th childre!
magicalhippo 7y ago
Because it makes you feel good from sounding like you've just accomplished a feat when you commit the feature.
JMTQp8lwXL 7y ago
Commit messages should be short. If you're familiar with conventional commit syntax (and chances are, your team will tell you to follow it, if your repository follows it), then your mind will automatically expand 'feat' to 'feature'.
munk-a 7y ago
`feat` is only a saver over `feature` if you're making a descriptor that was optional into something required - I admit I've never worked with a public commit history but for our internal projects commit messages are expected to give some justification or explanation of the necessity of the change without any formatting specifically enforced (though we require branches to contain at least one commit that pulls in the related issue ticket #). I much prefer encoding structured information like this at the ticket level where history can be more easily corrected and items are expected to be visible for all of time.
dvcrn 7y ago
Titles of commit messages should be short and concise, any extra information can go into the body of the commit. A common guideline is to have the title capped at 50 characters. If you work on the CLI, having a concise git log is far easier to skim than having very long commit messages and if I want to know more about the commit, I will check the body. It's also what a lot of websites use to truncate the title. From my experience, a few characters less do matter (which is also why I dropped conventional commits and just use "Add blah blah to blah", "Fix typo in user-facing message").
Svoka 7y ago
And only saves you like 3 symbols. Made a pull request fixing it https://github.com/conventional-commits/conventionalcommits.org/pull/204 https://github.com/conventional-commits/conventionalcommits....
- vemv 7y ago
  You're not saving them any work by creating that PR. That's better discussed and agreed on in advance.

mohaba 7y ago

feat of strength or great strength of feet?

ledauphin 7y ago
...don't follow.

deleted 7y ago

[deleted]

rinchik 7y ago

Isn't wording a bit off? "scope" should describe what the commit DOES, not what you are personally DOING, and not what you were intended to DO. "body", optionally, describes WHY. Also it feels like more of a convention for a personal project with optional C(I|D) automation prerequisites. In a team there should be a clear and emphasized place for the issue tracking info (ticket number, task id etc etc)

GordonS 7y ago
I quite like the idea of `scope` for large, multi-component projects, so you can tell instantly from the commit message what component has been changed.

inlined 7y ago

SemVer is generally good practice but I don’t like promotion to religion. For example, during the pre-release of the firebase-functions SDK we shifted SemVer by one: 0.2.1 was a feature addition from 0.2.0 and a breaking change from 0.1. Similarly there are rare cases where I’ve swept breaking changes under the rug because they were severe bug or security fixes that affected a corner case unlikely to be seen in the wild.

hyperpape 7y ago
I believe the first one is semver: before 1.0, anything can change at any time. https://semver.org/ https://semver.org/

kazinator 7y ago

I'm sticking to the GNU ChangeLog format, thanks. https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs https://www.gnu.org/prep/standards/html_node/Change-Logs.htm... This widely used format gives details about what is being done to each function. This was designed to be used in a ChangeLog file, so it has to be adopted for repository use. We don't have to record the date and name, since that is in the commit meta-data. WE write a commit title, and then the ChangeLog entry becomes the details placed after the blank line. That entry is mandatory: no title-only commits! There can be one or more discussion paragraphs between the title and the ChangeLog entry. We know that these paragraphs aren't ChangeLog entry material because they don't begin with the asterisk. Like this: http://www.kylheku.com/cgit/txr/commit/?id=b2739251281d7f6ef4d30164101bdf2a8d537a72 http://www.kylheku.com/cgit/txr/commit/?id=b2739251281d7f6ef...

epage 7y ago
Personally, I feel like this style puts the focus on what rather than the why. I also dislike that it seems to be centered on multiple changes in one commit.

abtinf 7y ago

I’ve found the commit message guidelines at https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project https://git-scm.com/book/en/v2/Distributed-Git-Contributing-... to very helpful for clarity. “ The last thing to keep in mind is the commit message. Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation. The Git project requires that the more detailed explanation include your motivation for the change and contrast its implementation with previous behavior — this is a good guideline to follow. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug."”

nirvdrum 7y ago
50 chars seems pretty arbitrary to me. I'd rather have a useful commit message. I've seen some pretty contorted messages conveying no real info in order to meet an imaginary character limit.
- hakre 7y ago
  the 50 chars is for the subject. the commit message (body) has no character limit (apart from a character limit per line).
  - hoseja 7y ago
    It's still overly restrictive and ossified from terminals / email subjects or whatever.
  - nirvdrum 7y ago
    Right. But that's the limit I don't get. If I always have to view the expanded set of commit messages to understand anything about the commit, what's the value in a short subject? And why 50 chars? That's even more restrictive than the normal 72/76/80 chars.

andrewprock 7y ago

This strikes me as quintessential bike shedding, process for the sake of process.

AndrewHampton 7y ago

We've been following conventional commits for our front end code for the last year or so at my work. In other repositories, we've loosely followed the keep a change log conventions. I find conventional commits great when your repository will produce a package to be consumed by others. For example, conventional commits for our shared JS code helps us produce great change logs and helps us easily follow semver for the NPM packages our other applications use. However, I don't find it that useful in the the final applications, even counter productive, since it typically will take up quite a bit of space in the commit title. Many of our front end devs completely ignore title length conventions now.

jackcodes 7y ago
Why don’t they put the additional information in the body of the commit? I see this in nearly every company I go to - everyone rushing to skip over adding anything useful to the permanent log by using git commit -m rather than a plain got commit.
- _asummers 7y ago
  This is the place where (mentioned elsewhere in this thread) things like issue tracker links and other context can and _should_ go if you're using something like CC.
- AndrewHampton 7y ago
  Oh, we do. We are generally pretty great at filling in good details in the body. I didn't mention that originally because I didn't think it was noteworthy. The main problem is very commit titles that end up looking like: feat(SomeScope.OtherScope.Class): add support for abc and xyz option

Aeolun 7y ago

I don’t think this is so much to make your commit messages better, as it is to make sure that all of them can be automatically processed into changelog and semver updates.

_asummers 7y ago
This is the way to think about it. It's concise enough and has tooling in enough languages to where generating the changelog from the commit messages is just a CI step, but it doesn't offer much more. I like and have used Conventional Commits for several years, but the goal is just tooling around telling others what changed outside of reading the git log, e.g. PMs who want an HTML artifact.

notmyfuture 7y ago

For use cases where this level of rigour is desired, it would be nice to have real separate metadata vs. convention. Doing this by convention is unreliable.

wincent 7y ago
You can get a basic level of enforcement for free by turning on the "Semantic Pull Requests" bot that will let you know when you forget the type (or use an invalid one): https://github.com/probot/semantic-pull-requests https://github.com/probot/semantic-pull-requests It obviously won't catch your mistake if you forget to mark a breaking change as breaking, but it's a start.

epage 7y ago

At $DAYJOB, we organically switched from not having any formal style to having an internal formal style. People seemed to want the benefits of tooling integration and clearer communication. Right now, we are switching SCM's and are looking at adopting Conventional to replace our internal style. I've already started using Conventional and have really appreciated it. It makes it fast and succinct (remember, line length "requirements" in git) to get the information you need even in one-line logs. Also, it makes CHANGELOG maintenance easier, whether using an automated tool or doing it by-hand. Not happy with the other ones, I've created my own commit style validation tool, committed [0] and have deployed it on my open source projects. Like code style enforcement in CI, I like delegating this to a tool since it makes the requirement very clear for contributors. The one thing I'm disappointed with with Conventional is that they did not follow git conventions for multi-line trailers. [0] https://github.com/crate-ci/committed https://github.com/crate-ci/committed

mgoblu3 7y ago
Similar experience here. On really big teams sure, you can bike shed the format a ton, but they’re all relatively close enough but CC has some good tooling so we just ran with it. Results have been fine, didn’t waste a bunch of time debating it. Haven’t figured out a good way to integrate co-authors easily with it though.
- epage 7y ago
  Wouldn't Co-Authors just be a footer/trailer?

eyegor 7y ago

> When you used a type not of the spec, e.g. feet instead of feat This actually had me laughing quite a bit. Because of my love for dad jokes, here are some less conventional commits: "fete" : adding holiday support "braking change" : a change of pace "nix" : removing a featute "suffix" : adding a nice to have

zoomablemind 7y ago

Commit messages are just that - an additional communication tool. As long as any format helps keep the understanding within a team clear with a minimum of overhead, so be it. After all the commit message is secondary to the actual code committed. I'm sure everyone can share an episode when a nicely worded commit had to be followed up with an ugly 'Fix a typo' message. The most practical convention is the one that's automated to some degree, for example, issue/feature tag auto-linking or some template driven messages. Either way the message should not become an ultimate hoop to jump before the actual commit and one more thing to 'maintain', the code should be the focus. In my experience, a commit message describing the committed behavior (even when intended) helps tie the code to the overall scope. In case when it's a bugfix, it still must be tied to a correct expected behavior. So in some sense a commit message could serve as an auxilliary level of unit testing. Of course, I'd rather put an effort to enforce the actual practice of unit testing over structuring the commit messages.

pantalaimon 7y ago
> I'm sure everyone can share an episode when a nicely worded commit had to be followed up with an ugly 'Fix a typo' message. There is `git commit --fixup` and `git rebase -i --autosquash` for that ;)

jevgeni 7y ago

Imagine the following future: “Have you linted and unit tested your commit message?” “Junior Developer wanted. 10 years of Conventional Commits experience required.” “Download Conventionalizer! Now you can write Conventional Commits in plain English, having all the syntax automatically generated! (node, erlang OTP and Jerry’s pre-alpha TensorFlow binding library required. Windows support coming soon.)” Something tells me the authors are hard at work solving a problem nobody needs solving.

skrebbel 7y ago
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.
- wincent 7y ago
  > Why? The machine-readable part is useful for generating changelogs (eg. broken out by type) or implementing semver (eg. detecting breaking changes).
  - hakre 7y ago
    but isn't it an antipattern to generate change-logs from commit subject lines?
    - ratherbefuddled 7y ago
      Of course not. How else would you do it?
      - dchest 7y ago
        Make a human read the commit history (or tickets) and summarize changes in the language useful for users, not for developers.

boring_twenties 7y ago

This would be better if it was called the Committer Convenant.

t0astbread 7y ago

I do something like this but for branch names. This spec recommends a squash-merge workflow to turn branches into commits before merge. Why would I wanna do that? It seems like throwing away a lot of detail unnecessarily.

vemv 7y ago

prefixes such as "fix: " are better expressed at the bottom of the commit message body. They are metadata, and as such they shouldn't take more attention than the actual data. This matters when you are in a bug hunt in production - you want to find the culprit commit as efficiently as possible, without distractions.

dajohnson89 7y ago

maybe it's just me, but things like this sap half the fun out of development.

Karupan 7y ago

We’ve found conventional commits useful in our mono repo. Instead of letting the authors deal with versioning (which sometimes breaks dependencies), our build pipeline determines the semver from the commit messages. This has made it easier to deal with releases for around two dozen packages by developers spread across three different countries.

w_t_payne 7y ago

I have a system that creates commit messages automatically. The commit messages themselves are YAML so that they can contain various bits of metadata - current task id, timestamps for oldest/newest known builds associated with that task etc...

crististm 7y ago

I like best the irony of "refactor!". A breaking change with a title meaning there should not be semantic changes in the code...

sime2009 7y ago

I have to admit that in the GitHub and PR era I rarely look at individual commits or their messages. I look at whole PRs.

leerob 7y ago

Conventional commits pair nicely with a Lerna monorepo when deploying multiple JS packages at once. Auto-generated changelogs and automatic semver for packages. It's worked well for us over the past year. https://github.com/lerna/lerna/blob/master/commands/version/README.md#--conventional-commits https://github.com/lerna/lerna/blob/master/commands/version/...