Commit messages - Good practices

48,363 views
47,954 views

Published on

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.

Published in: Technology, News & Politics
0 Comments
70 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
48,363
On SlideShare
0
From Embeds
0
Number of Embeds
20,600
Actions
Shares
0
Downloads
128
Comments
0
Likes
70
Embeds 0
No embeds

No notes for slide

Commit messages - Good practices

  1. 1. Commit Messages Good Practices by Tarin Gamberini www.taringamberini.com CC BY-NC-SA 3.0
  2. 2. 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.
  3. 3. 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 ...
  4. 4. Usually Do No t write commit Messages ?!?
  5. 5. Commit Messages Why? Commit Messages Why?
  6. 6. Any software project is a collaborative project Any software project has at least two developers ... Commit Messages Why?
  7. 7. … the original developer Commit Messages Why? ... the original developer few months later
  8. 8. 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?
  9. 9. … what revision xyz was supposed to do Commit Messages Why?
  10. 10. Because when some requirement can be implemented several ways in the responsible developer will write, in revision xyz ... Commit Messages Why?
  11. 11. … why revision xyz was implemented in that way Commit Messages Why?
  12. 12. 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?
  13. 13. … why revision xyz was added Commit Messages Why?
  14. 14. Commit Messages How? Commit Messages hOW?
  15. 15. The following hints are based on experience code development, bug troubleshooting and code review across a number doing 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?
  16. 16. 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?
  17. 17. 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?
  18. 18. The first line Imperative Should be limited to 50 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 50 Commit Messages hOW?
  19. 19. The first line Imperative Should be limited to 50 chars Should not end with a period Commit Messages hOW? [ !!! 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 50
  20. 20. 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?
  21. 21. 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?
  22. 22. The second line Should be blank [ Further [ paragraphs came after a blank line Commit Messages hOW? 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
  23. 23. 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?
  24. 24. 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?
  25. 25. Subsequential lines Should be limited to 72 chars Detailed description of the change Commit Messages hOW? [ Switch libvirt get_cpu_info method over to use config APIs l na i rig lem O b pro hy W y wH Y wh s on i tat y i i m f an l I 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
  26. 26. 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?
  27. 27. External references Do not assume availability of external resources 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?
  28. 28. External references Do not assume availability of external resources Bug tracking integration Commit Messages hOW? 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
  29. 29. 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 ...
  30. 30. Amazing commit messages
  31. 31. 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
  32. 32. 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
  33. 33. 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

×