Conventional Commits: A specification for structured commit messages

Imagine the following future:<p>“Have you linted and unit tested your commit message?”<p>“Junior Developer wanted. 10 years of Conventional Commits experience required.”<p>“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.)”<p>Something tells me the authors are hard at work solving a problem nobody needs solving.

&gt; feat: a commit of the type feat introduces a new feature to the codebase<p>instead of &#x27;feat:&#x27;, why not &#x27;feature:&#x27;?<p>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?

I&#x27;m sticking to the GNU ChangeLog format, thanks.<p><a href="https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;html_node&#x2F;Change-Logs.html#Change-Logs" rel="nofollow">https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;html_node&#x2F;Change-Logs.htm...</a><p>This widely used format gives details about what is being done to each function.<p>This was designed to be used in a ChangeLog file, so it has to be adopted for repository use. We don&#x27;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&#x27;t ChangeLog entry material because they don&#x27;t begin with the asterisk.<p>Like this: <a href="http:&#x2F;&#x2F;www.kylheku.com&#x2F;cgit&#x2F;txr&#x2F;commit&#x2F;?id=b2739251281d7f6ef4d30164101bdf2a8d537a72" rel="nofollow">http:&#x2F;&#x2F;www.kylheku.com&#x2F;cgit&#x2F;txr&#x2F;commit&#x2F;?id=b2739251281d7f6ef...</a>

We&#x27;ve been following conventional commits for our front end code for the last year or so at my work. In other repositories, we&#x27;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.<p>However, I don&#x27;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.

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.

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.

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

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.<p>Right now, we are switching SCM&#x27;s and are looking at adopting Conventional to replace our internal style. I&#x27;ve already started using Conventional and have really appreciated it. It makes it fast and succinct (remember, line length &quot;requirements&quot; 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.<p>Not happy with the other ones, I&#x27;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.<p>The one thing I&#x27;m disappointed with with Conventional is that they did not follow git conventions for multi-line trailers.<p>[0] <a href="https:&#x2F;&#x2F;github.com&#x2F;crate-ci&#x2F;committed" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;crate-ci&#x2F;committed</a>

Isn&#x27;t wording a bit off? &quot;scope&quot; should describe what the commit <i></i>DOES<i></i>, not what you are personally DOING, and not what you were intended to DO.<p>&quot;body&quot;, optionally, describes WHY.<p>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)

I’ve found the commit message guidelines at <a href="https:&#x2F;&#x2F;git-scm.com&#x2F;book&#x2F;en&#x2F;v2&#x2F;Distributed-Git-Contributing-to-a-Project" rel="nofollow">https:&#x2F;&#x2F;git-scm.com&#x2F;book&#x2F;en&#x2F;v2&#x2F;Distributed-Git-Contributing-...</a> to very helpful for clarity.<p>“ 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: &quot;Fix bug&quot; and not &quot;Fixed bug&quot; or &quot;Fixes bug.&quot;”

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.

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.<p>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.

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.<p>After all the commit message is secondary to the actual code committed.<p>I&#x27;m sure everyone can share an episode when a nicely worded commit had to be followed up with an ugly &#x27;Fix a typo&#x27; message.<p>The most practical convention is the one that&#x27;s automated to some degree, for example, issue&#x2F;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 &#x27;maintain&#x27;, the code should be the focus.<p>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&#x27;s a bugfix, it still must be tied to a correct expected behavior.<p>So in some sense a commit message could serve as an auxilliary level of unit testing. Of course, I&#x27;d rather put an effort to enforce the actual practice of unit testing over structuring the commit messages.

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.

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

Conventional commits pair nicely with a Lerna monorepo when deploying multiple JS packages at once. Auto-generated changelogs and automatic semver for packages. It&#x27;s worked well for us over the past year.<p><a href="https:&#x2F;&#x2F;github.com&#x2F;lerna&#x2F;lerna&#x2F;blob&#x2F;master&#x2F;commands&#x2F;version&#x2F;README.md#--conventional-commits" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;lerna&#x2F;lerna&#x2F;blob&#x2F;master&#x2F;commands&#x2F;version&#x2F;...</a>

lost me at “feat”

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

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.

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

maybe it&#x27;s just me, but things like this sap half the fun out of development.

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&#x2F;newest known builds associated with that task etc...

feat of strength or great strength of feet?

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