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
