commit message conventions

[Intransition]

When I write commit messages I add a "team" prefix to the message,
generally `admin`, 'doc` or `test` followed by a colon, space, and
then message. e.g.

admin: Updated README to explain new config options

That's worked well for me personally, as it allows me to sort commit
messages by category. But recently I've started to really give YARD a
shake for documenting my code, and I've toyed with the idea of
changing my commit messages to reflect YARD style:

@admin Updated README to explain new config options

I'm not sure I like that as much though.

Are there any known conventions for this sort of thing? Anyone else
have suggestions or personal conventions for commit messages that they
use?

 

[John Feminella]

I greatly dislike that style, to be frank. My commit messages usually
take this form:

=3D=3D=3D=3D=3D
[short, one-line description of what the commit achieves written in
present tense] [metadata, typically referencing a ticket number]
[skip a line here]
[optional commit body to explain the commit in more detail or to
describe new conventions introduced, considerations, etc.]
=3D=3D=3D=3D=3D

In other words, commits should read like they're e-mails: a short
subject, followed by a blank line, followed by a body. Some examples
of real commits I've made recently:

=3D=3D=3D=3D=3D
Adds new /api/transactions routes for managing transaction resources
[finishes #1984]
=3D=3D=3D=3D=3D
Refactors DataLoader into smaller classes with more defined responsibilitie=
s
=3D=3D=3D=3D=3D
Deletes unneeded/deprecated references to LOAD_TIME constant

Use of the LOAD_TIME constant was deprecated on April 15th in commit
2094ed1. It's now been a couple of months and we told clients that it
would be officially discontinued on June 1, so it's safe to remove.
=3D=3D=3D=3D=3D

~ jf

 

[Anurag Priyam]

In other words, commits should read like they're e-mails: a short

subject, followed by a blank line, followed by a body.

A lot of OSS projects including Git do this. Optionally (depending on
their policies) you include a Signed-off-by: Your name <your email>
line to indicate that you are providing this patch under the licensing
terms of that project. Personally, I tend to dump whatever I was
thinking while making that commit into the commit message.

 

[brabuhr]

I greatly dislike that style, to be frank. My commit messages usually
take this form:

=3D=3D=3D=3D=3D
[short, one-line description of what the commit achieves written in
present tense] [metadata, typically referencing a ticket number]
[skip a line here]
[optional commit body to explain the commit in more detail or to
describe new conventions introduced, considerations, etc.]
=3D=3D=3D=3D=3D

git-commit(1)
Though not required, it=92s a good idea to begin the commit
message with a single short (less than 50 character) line
summarizing the change, followed by a blank line and then a
more thorough description. Tools that turn commits into email,
for example, use the first line on the Subject: line and the rest
of the commit in the body.

 

[Intransition]

git-commit(1)
=A0 =A0 Though not required, it=92s a good idea to begin the commit
=A0 =A0 message with a single short (less than 50 character) line
=A0 =A0 summarizing the change, followed by a blank line and then a
=A0 =A0 more thorough description. Tools that turn commits into email,
=A0 =A0 for example, use the first line on the Subject: line and the rest
=A0 =A0 of the commit in the body.

But what about a categorizing a commit?

 

[Michael Sokol]

On Jun 13, 9:13 am, (e-mail address removed) wrote:
=20
=20
But what about a categorizing a commit?
=20

I'm not exactly sure what kind of categorization you are talking about, is i=
t concerning the group of users it affects?

Most of the time, the ticket you reference to in your commit will be categor=
ized and will hold lots of necessary information.

Michael=

 

[John Feminella]

Agreed. Reference the ticket, which can hold all the data about what
goal is ultimately satisfied by the commit.

~ jf
--
John Feminella
Principal Consultant, BitsBuilder
LI: http://www.linkedin.com/in/johnxf
SO: http://stackoverflow.com/users/75170/

I'm not exactly sure what kind of categorization you are talking about, i=

s it concerning the group of users it affects?

Most of the time, the ticket you reference to in your commit will be cate=

gorized and will hold lots of necessary information.

 

[Anurag Priyam]

But what about a categorizing a commit?

Most of the time I stick a tag in the subject line like:

reportage: bucket correctly for lazy loaded properties

yada yada yada

I don't adhere to it very strictly though.

 

[Intransition]

Agreed. Reference the ticket, which can hold all the data about what
goal is ultimately satisfied by the commit.

Often a commit has no associated issue. Moreover that information is
usually off on a sever somewhere. I use a tool to produce a nice
readable history file --which is the main reason I add a category, so
it can present only the things that really need to be listed in that
file.

 

[Phillip Gawlowski]

Often a commit has no associated issue. Moreover that information is
usually off on a sever somewhere. I use a tool to produce a nice
readable history file =A0--which is the main reason I add a category, so
it can present only the things that really need to be listed in that
file.

Create a topic branch, commit, merge back into your master, parse
history for topic branches.

--=20
Phillip Gawlowski

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
=A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0-- Leibnitz

 

[Justin Collins]

But what about a categorizing a commit?

For projects that have a few parts, I've started using "[Category] blah
blah blah..." for the first line. Like, "[Parser] Fixed whatever parser
bug". Makes it easy to scan through the commits and know which are
relevant, and sometimes allows the commit message to be shorter by
providing compact context.

-Justin

 

[Intransition]

Create a topic branch, commit, merge back into your master, parse
history for topic branches.

The "parse history" could bare more explanation.

(BTW, your advice on using a, e.g. GPL3.txt instead COPYING.txt proved
a good approach, thanks.)

 

[Phillip Gawlowski]

The "parse history" could bare more explanation.

It's left as an exercise to the reader, since it's highly dependent on
the source control tool(s) you use.

But as an example:

Mercurial has style templates[0], which allow customizing output of,
for example, the "hg log" command, which allows outputting branch
information for a given changeset. So, it's just a matter of creating
a style template that you can parse for your own needs.


[0] http://hgbook.red-bean.com/read/customizing-the-output-of-mercurial.htm=
l

--=20
Phillip Gawlowski

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
=A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0-- Leibnitz

 

[brabuhr]

The "parse history" could bare more explanation.

It's left as an exercise to the reader, since it's highly dependent on
the source control tool(s) you use.

But as an example:

Mercurial has style templates[0], which allow customizing output of,
for example, the "hg log" command, which allows outputting branch
information for a given changeset.

With git, on the commit message side of things, you can use a template
to help standardize the messages, e.g.:
[short subject here]

[long description here]

References
* [ticket number]
* [etc...]

On the log viewing side, git provides some canned output formats and
also a flexible format-string option.

git-log(1)
format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
would show something like this:
The author of fe6e0ee was Junio C Hamano, 23 hours ago
The title was >>t4119: test autocomputing -p<n> for
traditional diff input.<<

* http://spheredev.org/wiki/Git_for_the_lazy#Writing_good_commit_messages
* http://www.jukie.net/bart/blog/pimping-out-git-log