Commit Messages

Good Practices

by
Tarin Gamberini
www.taringamberini.com
CC BY-NC-SA 3.0
 Abstract
An extremely little set of rules to write
good commit messages.
History (how code changes over time)
become a very useful tool if associated with
good commit messages.
These slides would make developers more
aware about how good commit messages
could improve their work.
Usually do not write
commit messages
I have said to my cat
that some developers
usually do not write
commit messages
My cat could not belive it ...
Usually
Do No t write
commit
Messages
?!?
 Commit Messages
Why?

Commit Messages Why?

 Any software project is a
collaborative project

Any software project has

at least two developers ...

Commit Messages Why?

 ... the
… the
original developer
original developer
few months later

Commit Messages Why?

 Because when some
poor maintainer is
hunting a bug
and finds that it was
added in revision xyz,
he will want to know ...

Commit Messages Why?

 … what revision xyz
was supposed to do

Commit Messages Why?

 Because when some
requirement can be
implemented in
several ways the
responsible developer
will write, in revision
xyz ...

Commit Messages Why?

 … why revision xyz was
implemented in that way

Commit Messages Why?

 Because when the boss
wants to know why
a functionality was
added, and the developer finds
that happened in revision
xyz, the developer will
want to know ...

Commit Messages Why?

 … why revision xyz
was added

Commit Messages Why?

 Commit Messages
How?

Commit Messages hOW?

 The following hints are
based on experience
code development,
doing
bug troubleshooting and
code review across a number
of projects using GIT

Examination of other projects

Such as the Kernel, CoreUtils,
GNULIB and more suggested
they all follow a fairly
common practice
Commit Messages hOW?
 The first line

[ Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 The first line
Imperative
!!!
[ Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 The first line
Imperative
!!!
Should be [ Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

limited to
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

50 chars Closes-Bug: #1003373

Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

50

Commit Messages hOW?

 The first line
Imperative
!!!
Should be [ Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

limited to
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

50 chars Closes-Bug: #1003373

Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Should
not end 50
with a period

Commit Messages hOW?

 The second line

[
Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 The second line
Should be
blank
[
Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 The second line
Should be
blank
[
Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

Further
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

paragraphs [ Closes-Bug: #1003373

Implements: blueprint libvirt-xml-cpu-model

came after a
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

blank line

Commit Messages hOW?

 Subsequential lines

Switch libvirt get_cpu_info method over to use config APIs

[
The get_cpu_info method in the libvirt driver currently uses XPath
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 Subsequential lines
Should be
limited to
72 chars Switch libvirt get_cpu_info method over to use config APIs

[
The get_cpu_info method in the libvirt driver currently uses XPath
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

72

Commit Messages hOW?

 Subsequential lines
Should be
limited to
72 chars Switch libvirt get_cpu_info method over to use config APIs
l s

[
a h y on
n
igi lem ti
The get_cpu_info method in the libvirt driver currently uses XPath
W y ta
r i
queries to extract information from the capabilities XML document.
wH Y y
O b il m f an
Switch this over to use the new config class LibvirtConfigCaps. Also

pro wh I
provide a test case to validate the data being returned.

Detailed Closes-Bug: #1003373

Implements: blueprint libvirt-xml-cpu-model

description of
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

the change
72

Commit Messages hOW?

 External references

Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

[
Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 External references
Do not assume
availability
of external Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

resources
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

[
Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Commit Messages hOW?

 External references
Do not assume
availability
of external Switch libvirt get_cpu_info method over to use config APIs

The get_cpu_info method in the libvirt driver currently uses XPath

resources
queries to extract information from the capabilities XML document.
Switch this over to use the new config class LibvirtConfigCaps. Also
provide a test case to validate the data being returned.

Bug tracking
[
Closes-Bug: #1003373
Implements: blueprint libvirt-xml-cpu-model
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

integration

Commit Messages hOW?

 Usually write
commit messages
I have said to my cat
that now those developers
are getting used to writing
amazing commit messages
My cat was astonished ...
 Amazing
commit messages
 Bibliography
Why should I write a commit message?
http://programmers.stackexchange.com/questions/52267/why-should-i-write-a-commit-mess
age
GIT Commit Good Practice
https://wiki.openstack.org/wiki/GitCommitMessages

A Note About Git Commit Messages

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Best Practices for Version Control

http://blog.looplabel.net/2008/07/28/best-practices-for-version-control/

On commit messages
http://who-t.blogspot.de/2009/12/on-commit-messages.html

Subversion Best Practices

http://svn.apache.org/repos/asf/subversion/trunk/doc/user/svn-best-practices.html

Redmine - Administration Guide - Referencing issues in commit messages

http://www.redmine.org/projects/redmine/wiki/RedmineSettings#Referencing-issues-in-com
mit-messages
Is Multiple-Column Online Text Better? It Depends!
http://psychology.wichita.edu/surl/usabilitynews/72/columns.asp
 Images attribution
Slide 4
“frightened cat” from Simon Video at
http://www.simonvideo.com/iphone-ipod-touch/how-to-downgrade-your-iphone-os-4-0-bet
a-3g-on-a-mac/
Slide 7
“the original developer” from High Cats Wallpapers Quality at
http://daveandmonicamunson.blogspot.it/2012/04/high-cats-wallpapers-quality.html
“the original developer few month later” from Fun and Fitness at Fifty at
http://fitnessandfunatfifty.wordpress.com/2012/12/07/where-the-heck-did-i-hide-those-presen
ts/forgetful-cat/
Slide 9
“hunting a bug” from Movie Posters – feedio.net at
http://img.thesun.co.uk/multimedia/archive/01249/Monkey-massaging-c_1249605a.jpg

Slide 11
“orange cat” from Fanpop at
http://www.fanpop.com/clubs/think-different/images/31463891/title/orange-cat-photo
 Images attribution
Slide 13
“the boss wants to know” from HD Wallpapers, Images and Photos at
http://hdwallpaperen.com/wp-content/uploads/2013/09/Funny-Baby-And-Cat-HD-Wallpaper.
jpg
Slide 15
“git logo” from SILICON ANGLE at
http://siliconangle.com/blog/2012/07/09/social-network-for-developers-github-raises-monst
er-series-a-round-funding-100m/
Slide 30
“astonished cat” from Can it be Saturday Now at
http://canitbesaturdaynow.com/images/fpics/3244/1264885670882__large.jpg