
Commit messages are not titles (2015) - arkadiytehgraet
http://antirez.com/news/90
======
caseymarquis
Commit messages are whatever an individual, community, or organization decides
they should be. Debating beyond that is like debating tabs vs spaces. It
doesn't matter as long as everyone you're working with is on the same page.

~~~
protonimitate
The "rule" I like when it comes to commit messages it that they should be
clear enough that someone who gets woken up for a production issue at 3am can
quickly parse what was in the commit and how dangerous it is.

Nothings worse than digging through a ton of diffs to find the breaking
change.

~~~
lmm
I find that requiring "nice" commit messages tends to mean digging through
bigger diffs to find the breaking change. If you're fine with commit messages
like "fix" or "derp", then people are more willing to make each tiny change a
separate commit, and then a git bisect takes you right to the specific diff
that caused the problem.

~~~
pjc50
Absolutely not! Submitting "derp" to code review is just disrespectful of the
reviewer's time.

There's a rationale for every change. The submitter knows it. The reviewer
needs to know it. They can try reconstructing it from the diff, which is
potentially error prone .. or you could just tell them.

I'll accept "Fix ticket #1234", since that's moved the rationale elsewhere.

~~~
lmm
A PR needs a review and a written rationale, agreed, but that doesn't mean
each individual commit does (indeed one usually reviews the diff as a whole,
not the individual commits). Commit everything that compiles, make the PRs at
a coarser granularity, then you get the best of both worlds.

------
awolf
> If the first line of a commit message is a title, it changes the way you
> write it. It becomes just some text to introduce some more text, _without
> any stress on the information density_.

I agree with the author that commit messages should optimize for information
density. However the example they provide does a poor job of this:

> This is a smart synopsis, as information dense as possible.

"This is a" is the type of thing that should never appear in a commit message
as it could apply to EVERY commit message. Synopsizing is the action, but
doesn't indicate what is being synopsized; one of the most important facts for
someone to understand what is happening here. Finally "as information dense as
possible", again should also be cut as this is telling us HOW not WHAT (and
ironically hurts information density).

Were I writing this example it would be:

    
    
      Synopsize how to write a commit message
    

\---

I led an initiative at my current company to enforce all commit messages start
with an imperative verb and be less than 72 characters. Some people hate it,
some people love it.

Aside from standardization, the primary reason to do this is the imperative
mood leads to the most concise sentence possible. By leading with the action,
the most natural thing to do next is to talk about what is being acted upon.
Unnecessary words are dropped and the most important facts are emphasized. In
short it forces the author to get to the point.

    
    
      [Act] upon [some aspect of the code]
    

e.g.

    
    
      Add user login link on home screen
      Refactor authentication into separate classes
      Lint PR titles conform to standard format

~~~
schrodinger
> I led an initiative at my current company to enforce all commit messages
> start with an imperative verb and be less than 72 characters.

You are truly doing god’s work :). I’ve led a similar initiative and same
outcome, some love, but those who don’t, really hate it.

~~~
heavenlyblue
Why do they hate it? Are those the creative ones that can’t conform?

------
st_goliath
There is probably no reasonable, generic guide on how to write commit
messages, since different communities use git in different ways. So IMO this
article is comparable to a discussion about indentation styles or text
editors.

> Commit messages are not titles

> Nor subjects, for what matters.

> ...

> however many times there is _no_ body, there is just the first line.

In Linux (the Kernel) development (where git actually came from), commits are
sent as patches via e-mail to mailing list for review and for maintainers to
pick them up.

The first line from the commit message becomes the subject line, the rest of
the commit message and the diff becomes the body of the mail. The commit
message should briefly explain _why_ you are doing this, the _what_ should be
mostly in the diff itself. Having no body text after the first line for a non-
trivial patch would be rather bad practice. Obviously the author of this
article comes from a different background.

But then again, in different communities, a concise single line description
with a ticket number may be enough.

------
mceachen
Capturing the _reason why_ something was changed, why this approach was
chosen, and possibly enumerating other approaches not taken (and why they
weren't picked), are all gold to the Engineers of Tomorrow spelunking into
some codebase.

Summarizing a diff frequently doesn't add information that the diff itself
already includes. Title or no title.

I'm surprised we don't think about how to shout into the future more
effectively. It might be ourselves that we're helping the most.

~~~
kzzzznot
I think capTuring the “why” of a commit is often overlooked but highly
valuable.

------
sovietcattle
Trying to impose "one way" to write commit messages is silly at best.

At work I follow whatever convention the team I'm on agrees with.

For my projects I use commit messages as a way to "tag" changes, more than to
explain the changes using prose. That way it's very easy for me to search for
changes in the codebase.

eg. #event-loop #fix #multiple-dispatch #repeated-message (remove the # and
you get the idea)

------
thrower123
Most commit messages look like this:

    
    
        #1234 fixed the fucking fooinater that wouldn't frobulate.
    

Thank god for the hash ticket number linking standard. Unless you are working
on the kernel, your context and discussions and notes are in the bugtracker,
so there's no very good reason to write an essay in the commit log.

~~~
reificator
Until you switch bug trackers and the import process subtly mangles that link,
and then you switch trackers a few years later and all hope is lost, and then
five years after that you hire someone to fix all the bugs that you've been
accumulating and they can't tell any of the reasoning behind anything you've
done.

Are you always going to be on Jira? On Github? When people fork your project
are they expected to clone your issues as well? When you migrate to another
system are all your issue references still going to line up correctly? Did you
even think to check?

Please continue to include the ticket reference. But also put some context in
your commit message because that's what it's there for.

This is the same reason that even if you use a fancy documentation site, it
should be generated from files in the repo.

~~~
bagacrap
Broadly speaking, so much documentation is on the issue tracker, that yes, I
expect efforts to be made to preserve that content in perpetuity in one way or
another.

------
mcguire
The first comment:

" _Every source control management system has its own rules. So what I say
here for Git might not be valid for Mercurial, SVN, Bazaar, ..._

" _Git has a wonderful tool named format-patch,[http://git-
scm.com/docs/git...](http://git-scm.com/docs/git...), that takes a commit and
converts it to an email, to put it in a nutshell. Why is there a tool for
that? Because Git was created to manage Linux kernel development, and that is
done in most parts in or around the Linux Kernel Mailing List. So, the
entanglement between commits and emails is deep rooted in Git. And yes, the
first line of the commit message _is_ used as the subject._

" _This explains, why you can google "git commit message" and find the same
advice over and over again:_

" _[http://git-scm.com/docs/git...*](http://git-scm.com/docs/git...*)
"_[https://github.com/erlang/o...*](https://github.com/erlang/o...*) "
_[http://tbaggery.com/2008/04...*](http://tbaggery.com/2008/04...*)

"_"No dot at the end, because it might end up as email subject, also use 50
chars or less."*

" _I agree, that interpreting it as title for a longer commit message is a bad
idea. The conciseness of this line is something important to be retained. A
well-crafted email subject on the other hand makes in some cases reading the
whole email unnecessary or only complimentary. (Yes, such things exist.) And
that are the types of commit messages that we should strive for, ending with a
dot or not._ "

------
dang
Discussed at the time:
[https://news.ycombinator.com/item?id=9763463](https://news.ycombinator.com/item?id=9763463)

------
boomka
Best practice advice used to be "dont leave your commit message empty" and now
it seems headed in a direction of some kind of storytelling guide. Up next:
the role of character development in your commit messages

~~~
gpderetta
Show, don't tell!

------
xwdv
Commit messages are not titles, or subjects, they are COMMANDS, written in the
present tense, that describe exactly what will be done to the codebase if you
merge in the commit. That’s pretty much all there is to say about it.

~~~
ticmasta
Well, I'll say more...

They are a summary of what will happen if the commit (which is a bunch of
commands) is applied.

They also can elaborate on the context around the commit. It's thoughtful of
the commiter if your coworkers don't need to dive into the detailed changes to
get a broad picture of why the commit exists.

~~~
brian_cunnie
This.

Also, commit messages are sometimes the "documentation of last resort".

In my organization, putting comments in the code is frowned upon. "Comments
are lies! The documentation is in the tests!"

But the tests don't lend themselves to _reasons_ behind why the code was
written a certain way, why a given approach was taken (for example, we needed
to re-write a Rails database migration in a somewhat contorted manner to avoid
a deadlock that was occurring in production).

In such organizations, the git commit message are often the best place to warn
future programmers of pitfalls: "don't even think of parallelizing these table
updates—you'll get deadlocks!"

[edited for brevity]

~~~
brigandish
The _why_ is the thing most often missing from documentation of any sort. I
often find myself looking at the README for a library I've not heard of and
wondering what it will do for me because it only states the _what_ , the _why_
often tells me the/a problem the library solves.

> Foobar packs JSON into binary

vs

> Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar)
> that packs JSON into a binary format. Now our messages are 50% smaller and
> 30% faster.

Git commit messages are worse offenders but there's plenty of criminals about!

------
mc3
Just use {JIRA Reference} - {JIRA title} and get on with your life.

~~~
seattle_spring
The irony of this comment being that managing JIRA tickets is probably the
absolute biggest time-sink of any organization that uses it.

~~~
mc3
I find JIRA light weight. The trick is not to follow too many processes. Drag
on tickets to your board when you start them and move then through the swim
lanes. The worst cases are when people set up too much security and complex
transition rules so that people are blocked by JIRA.

JIRA ain't perfect though. The constant UX changes drive me nuts. At least HN
still works the same way as 10 years ago, but JIRA keeps changing like a
shapeshifter.

~~~
seattle_spring
The fact that larger companies that use JIRA have to employ full time "JIRA
Administrators", or worse, _teams_ of JIRA admins, suggests that the tool is
anything but lightweight.

~~~
mc3
Larger companies need meta-roles. That is never going away. If that "PMO"
person isn't using JIRA, they are using something else, or there are even more
people wasting time dealing with all this via email and shared Excel sheets.

------
gumby
Why should a message subject not end with a period?

