Subject-First Commit Messages

TBH, at least at every company I've worked at recently, the style of the commits is more or less irrelevant to me save for one very important piece: The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). The biggest benefit of this is that these commits can then be automatically linked to the ticket which often has a lot more detail and conversation.

99% of the time when I'm looking at commit history, I'm not just generically scanning. I'm usually looking for a particular change, or when something touched a particular file, etc. Even the example given in the linked page isn't really relevant to me, because I'm rarely "quickly scanning" a whole commit log for something in particular - I'd always just use a search feature (in GitHub or some git IDE plugin) for that.

I look at commit messages every day. I actually don't love a message that just describes the code change (I can figure that out on my own if I look at it long enough). That's fine for bigger or more misleading changes, but when I'm looking at blame/history I'm usually very aware of what the code is doing already. My question at those times is less about "what" and more about "why". Why was this change made? Sometimes that can be found by looking at accompanying tests (if the original author was so gracious), but if it's not in the commit (or only obtusely so, as many developers I know tend to commit in what I'll call "stream-of-consciousness" style) then I've got to go outside the codebase to research by interviewing people (assuming they're still around and remember) or trawling through our project management system to try and line up released features/fixes with the change. It quickly becomes an inexact science.

That said, in my experience, the larger an organization, the more commit messages get looked at. On my side projects where only 1-3 people are involved, commit messages only really show up on the PRs as things are going in. Sometimes we complete our own PRs to keep up the velocity since we're all working async part-time. Rarely if ever do we look back to figure out why we did something because the project is so small.

I personally prefer conventional commits.

https://www.conventionalcommits.org/en/v1.0.0/

The subject line says what the purpose of the change is (CI/CD, tests, bug fix, new feauture), what component it primarily focuses on, and then a plain text one line summary.

For example:

    ci(GitLab): Add rust build directory to cache
    
    This should improve build times by caching most of the compile tree between builds. In testing, I’ve observed builds drop from 2m to 30s when scheduled on a node with a primed cache.

It also forces me to keep my commits focused. If I can’t create a one line summary of what I’ve done, it probably needs to be broken up into multiple commits.

I think I would prefer this style.

And also the discourse around commit messages and their various flavors may be one of the biggest wastes of time in terms of ROI in our industry.

I’ve been doing this for 14-15 years and can probably count on two hands the number of times I’ve needed to look at historical commit messages.

The subject-first style felt grating at first, but comparing the two I found myself reading more per line than I did in the verb-first approach.

Fix skip fix skip fix skip add skip

I knew nothing at the end. The second style had me grasp more, as there were no obvious hooks to skip without knowing what had changed.

But as others have said, commit messages are a cesspool of bikeshedding and ultimately useless, unless every commit is a self-contained chunk of work which it rarely is.

On the side, I enjoyed all of this author's thoughts in the repo. Good find.

I like a style like:

codebase section: short summary

longer description if necessary

eg: cocoaui: fix images being incorrectly aligned on high dpi displays

We were calculating the position of the image in logical pixels, but not converting that to actual display pixels for rendering.

I think it's a really nice style that makes commit messages really easy to scan in a short log, and lets you ignore commits easily that don't touch the area you're interested in

Spent 5 minutes trying to figure out where field_name is in the second list... I thought it was the same commits rewritten to be more scannable, but they are from a different project.

(I scanned, naturally, the article itself!)

Or more generally, I thought the point of the article would be that the function / variable names from the first list would be moved to the beginning of sentences. But in the 2nd example they are completely absent, favoring much vaguer / high level descriptions. So we are unable to see the before/after effect for the same list of commits, I think most of the potential impact of the author's intended point is lost.

(Also, the first half extolls the virtues of being able to read quickly, while the second half tells you to use longer sentences for everything for apparently no reason?)

Like everything in software development, this is just personal preference without any actual evidence, a substitute for actually making software with quantitative quality metrics that users actually care about. Let's fiddle with our commit messages, PR formats, code formatting, etc. etc. etc. instead of addressing the fact that our website has 6 different fonts and makes 30 HTTP requests to show a few hundred bytes of text.

This seems super subjective, while being written as if it's not.

I find this way WAY harder to read/scan, and very much prefer Google's standard: https://google.github.io/eng-practices/review/developer/cl-d...

In my experience consistency is more important than any specific style of commit messages. Similar to style guides for code; there's plenty of ways to approach it, but the real value is the consistency in how things are written across all developers.

> The second style likely feels foreign, and possibly uncomfortable. It's passive voice and present tense — all the things that we aren't supposed to make our commit messages.

Nitpick: it's passive voice and indicative mood (and sometimes subjunctive) -- there's nothing wrong with present tense. "Fix typo" is active voice, present tense, and imperative mood. (The Rails commits that dip into past tense bother me slightly, but whatever.)

Broadly, I have a few opinions on commit messages. The style doesn't really matter as much to me, although I'm a relatively strong adherent to "one-line summary, followed by paragraph(s) of additional context" (as is standard in the Linux kernel, and supposed best practice at Google even if it isn't universal by a long shot).

One is that the commit message should be useful for anchoring a search for potentially relevant changes, and for providing broader context re: why the change was made.

At the same time, I waffle between putting more description in the commit message, versus just commenting the code (or making the code clearer).

The last is more pragmatic: when I'm searching for a specific change, I'm often looking at the history of a particular file (blame or otherwise). I can quickly filter out all the "fix typo" messages or "[LSC]" (large-scale change, term used at Google for various company-wide code health refactors). Or if I'm trying to figure out which change introduced a bug, I'll probably bisect it one way or another (I often try to short-circuit that bisection toward the end to save the last few iterations). Either way, I don't actually spend that much time reading through commit messages until I've identified a potentially problematic change.

there are pros and cons to both verb-first and subject-first commit styles.

verb-first commits can be organised in a few categories. since they are few commit verbs (fix, add, refact..), always use the same verb prefix for bug, features messages and you will have nice categories to scan/filter:

- add feature

- fix bug

- refactor logic

On the other hand, subject-first indeed put the important part first and let you search for a term:

- Instance configure template method called from constructor

- Store's project method is an alias for fetch

- Title is changed

Depending on the use case, are you often searching for something? or would you like to highligh the nb of bugs/features in the last release?, one style is better suited than the other.

For important changes, I like the linux kernel style: oneline summary, details (problem, impact, solution..)

https://docs.kernel.org/process/submitting-patches.html

I like to be able to read the commit line following the sentence: "This commit shall ...".

For example from TFA:

"Fix code example in the field_name method"

gives:

"This commit shall fix code example in the field_name method".

OK, cool, I may or may not merge it, pull it, whatever-it. But I know what it'll do should I use it.

Now from what TFA recommends:

"Default reader batch size is 1000"

Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information.

I'll pass and keep using the "best practice".

Using the best practices the commit would read:

"Change default reader batch size to 500" or "Change default reader batch size to 1000" or maybe "Add default reader batch size" (btw the commit line in TFA is so bad that I'm not sure at all it's 500 or 1000 or something else I should put here to make my point).

The "best practices" aren't a bias. They're the result of people thinking long and hard as to how to make commit lines as clear as possible.

I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects.

After started using conventional commits [1] for my messages the style of Subject-First commit messages comes almost naturally.

[1] https://www.conventionalcommits.org/en/v1.0.0/

I prefer the first style. It reads way less weirdly. I spend way more time reading commit messages than "manually searching" by scanning them. I either arrive at the commit from git blame, or I use this really cool feature of computers called "ctrl-F".

Past commit messages have 2 uses to me.

- Blame view, where I usually want to know the ticket number so I can track down a story which has the business rules the dev was implementing.

- Bisect, where I want to know if this works or not without having to do a test run every time.

This format is alright I guess, but the best thing you can do honestly is just

TICKET: [done/works but wip/does not work] [describe what you’re thinking]

AB-1234: does not work, trying to rewrite this controller to remove all the duplication, /api removed temporarily

To me, that doesn’t have to be set in stone. No one likes working with a commit message stickler when standardized formats are only useful ~20 times a year to save 10 minutes each. (In my experience)

Error messages. Get to the meat of it in the first 3 words, there's a high chance that's the only part that will get read, or even displayed. It must be the most meaningful part of the error message.

I find commit messages are more useful when we consider machines to be primary the consumers of them.

Using conventional commit style messages allow us to generate changelogs and modify our semver versions automatically. Generating changelogs by hand is extremely tedious. Modifying semver by hand leads to caring too much about the number.

Like others have pointed out, the context and "why" can easily be tracked by linking out to the ticket/task that the work is associated with.

I go the other extreme and do below as commit messages.

https://keepachangelog.com

Makes creating change logs super easy & clear.

Which is prefacing each commit with either:

  ADDED for new features.
  CHANGED for changes in existing functionality.
  DEPRECATED for soon-to-be removed features.
  REMOVED for now removed features.
  FIXED for any bug fixes.
  SECURITY in case of vulnerabilities.

I’m against any style or enforcement of style of commit messages that breaks changelog

I use git log history for changelogs with a little dressing for markdown. I could pull this from Jira but it’s worse. Stories aren’t changes.

So I understand that some folks use git log for history and care about their code style so much as to enforce commit message stylecop, it’s overkill in my world and would only cause you to have to amend your commit or write a new message on squash.

The problem with the experiment is that when I’m scanning, typically I’m never scanning and then getting tested on the contents after the fact. It actually took me longer to spot any mention of store in the second example after being told what I was looking for than it did for me to find field_name after being told to look for it. YMMV.

The rationale of subject-first is clear. But what about the other rules: correct instead of fix, rather than instead of rename... They seem pretty arbitrary to me.

This doesn’t work with conventional commits which is flat out awesome. But I will try mixing both because I like the idea

Strong disagree.

Commits are actions and should place actions first.

If you need to find a specific item, that is what `git log --grep` is for.

Ehhh... maybe. One implicit trade-off here is how low detail the second set is, and that'll happen any time you force a structure - mandated structure takes more space on average, sometimes significantly more. Passive voice wastes a lot of space too (in English anyway).

Personally I think this is better solved by a changelog doc (which you can wordsmith for outsiders, which is an entirely different target than internal developers) and `git blame` (I never browse all of history to find changes to a method, just blame it for the latest or `git log -p -L` to check a series of changes to a file/func/etc).

Bottom line first. I like it.

Some additional context on this:

- There are additional organizational and process mechanics in-play that are out-of-scope for just a write-up on commit messages

- The team is made up of around 15 people supporting around 400 repos and about 8 live products

- The team DOES NOT use pull requests. Contributors are expected to be socially capable and fully engaged in the inter-personal, realtime communication that supports high-performance, low-handoff work.

- The ticketing system is NOT the primary means of communication between team members. It's merely a catalog of work items with only high-level supporting notes. A work item, as the old saying goes, is a "placeholder for a conversation", rather than a work order that can be executed upon by a contributor operating in isolation.

- The original author is describing an exceptional software product organization. He's not debating the merits of various subjective perspectives on what kind of personal flair might drive the content of commit messages. Instead, he's describing one small piece of a methodology that explicitly discourages personal flair and explicitly encourages (and provides supports for) direct communication, and rigorous attention to the team's well-considered, proven, and communicated norms.

- Contributors on the team are expected to maintain their own work logs in the spirit of engineer's logs from engineering industries. If the "why" of a change is important, it will be recorded in the work log. Senior technical leaders (at a minimum) keep up with the individual work logs looking for hazards and maintaining an understanding of the learning that's taking place in the team.

- Contributors on the team are expected to maintain equipment logs for the components that they're making changes to. This isn't the same thing as a SCM log, as an SCM log is for the SCM, not the product under development.

- The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors. It's about training developers (and designers, and operators, etc) to be more objective about the work they do, and to communicate it in an objective way. Mentions of "changed", "fixed", etc, are records from the perspective of the worker, not the product. When scanning the list of changes made to a work product, the team members are primarily interested in the impacts to that piece of equipment first and foremost. The work product change logs are voiced in terms of the work product, and not the worker. Again, the reflections, learning, questions, observations, etc, of the humans involved in the work go into the human's own logs, and are supported by the person-to-person processes that are beyond the scope of the article on commit messages.

- These 15 people with their 400 repos and 8 live products was winning industry awards within a couple months of go-live within the first year of the team's charter. There's nothing average about the team, the product, and the methods in-play. The commit messages are just one detail of the finely-honed process and culture that were intentionally designed, socialized, and painstakingly-supported to achieve its objectives.

- The author of the article is describing one facet of an overall product development system for a high-performance software organization. He's not trying to spark a dialog about the myriad opinions of how commit messages are written across the breadth of software development within processes and cultures that may not go much beyond the cross-referencing of items between ticketing systems with an SCM system, which is arguably a higher-ceremony approach from an artifacts perspective, but also a "bare minimum" from a process and culture perspective.

It's not entirely pertinent, but just in case there's some question as to whether this work is being done in a business of some scale or other at some particular time or other in a business's lifecycle that accounts for how the development system works, and whether it's a special case: the business context of team's work is a $1B multi-national with about 2,000 employees working in the regulatory side of corporate law, finance, and venture capital.

The business context isn't the enabling factor or the deciding factor. The product development system in-effect is the key factor, and it was shaped explicitly for its outcomes irrespective of the business context. The development system has been used at various companies up-and-down the axis of business scale and scope.

The single greatest contributing factor of the team and its work is that they carry very little technical debt, and the methodology required to work this way touches every molecule of process, organization, and culture. It would not be recognizable from the perspective of typical mid-curve software development, and it would not be understood by examining any single process element in isolation.

Meh, as in this doesn’t feel like it really matters. Like other commenters, there are exceptionally few situations when I find myself just reading the commit log, so the claimed psychological advantage appears moot in the context of the common/standard software development process (which is very much not what author’s team does, so I acknowledge this approach brings specific measurable advantages for them).

When I do need to read the commit log, it’s typically for a third party component and I look for broad categories I need to pay attention to (security fix? Behaviour change?) — this aligns well with the conventional commits standard and well managed release notes. But, to not have to read commit logs, we also do the rest of the conventional software development workflow (PRs, team meetings, etc) that serves to build the awareness of what’s being done.

I like the first concept.

I prefer the first version, I didn't find the second version to be more "scannable" and it seems to me to be more esoteric requiring study to realize what was recorded. The first version is clear, each commit makes sense and is what I'd be grepping for when trying to find a commit.

commit messages are a code smell. If you need to commit code, then you’ve already made a mistake

Verb-first is already the subject. We fill in the latter portion of a sentence that begins (in our head), "When merged, this commit will..."