When I write commit messages I add a “team” prefix to the message,
generally admin, 'docortest` 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?
I greatly dislike that style, to be frank. My commit messages usually
take this form:
=====
[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.]
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:
=====
Adds new /api/transactions routes for managing transaction resources
[finishes #1984]
Refactors DataLoader into smaller classes with more defined
responsibilities
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.
~ jf
John F.
Principal Consultant, BitsBuilder
LI: http://www.linkedin.com/in/johnxf
SO: User John Feminella - Stack Overflow
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
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.
On Jun 13, 9:13am, [email protected] wrote:
git-commit(1)
Though not required, its 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.
But what about a categorizing a commit?
On Mon, Jun 13, 2011 at 7:58 AM, John F. [email protected]
wrote:
I greatly dislike that style, to be frank. My commit messages usually
take this form:
=====
[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.]
git-commit(1)
Though not required, its 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.
Agreed. Reference the ticket, which can hold all the data about what
goal is ultimately satisfied by the commit.
~ jf
John F.
Principal Consultant, BitsBuilder
LI: http://www.linkedin.com/in/johnxf
SO: User John Feminella - Stack Overflow
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.
On Jun 13, 2011, at 9:55 AM, Intransition [email protected] wrote:
But what about a categorizing a commit?
I’m not exactly sure what kind of categorization you are talking about,
is it concerning the group of users it affects?
Most of the time, the ticket you reference to in your commit will be
categorized and will hold lots of necessary information.
Michael
On Mon, Jun 13, 2011 at 5:18 PM, Intransition [email protected]
wrote:
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.
Create a topic branch, commit, merge back into your master, parse
history for topic branches.
–
Phillip G.
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.
– Leibnitz
On Jun 13, 10:37am, John F. [email protected] wrote:
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.
On 06/13/2011 06:55 AM, Intransition wrote:
On Jun 13, 12:37pm, Phillip G. [email protected]
wrote:
On Mon, Jun 13, 2011 at 5:18 PM, Intransition [email protected] wrote:
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.
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.)
On Tue, Jun 14, 2011 at 1:47 PM, Phillip G.
[email protected] wrote:
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 for
traditional diff input.<<
http://spheredev.org/wiki/Git_for_the_lazy#Writing_good_commit_messages
On Tue, Jun 14, 2011 at 7:26 PM, Intransition [email protected]
wrote:
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.html
–
Phillip G.
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.
– Leibnitz