Commit messages - Good practices
80 likes67,372 views
This document outlines best practices for writing effective commit messages in software development, emphasizing their importance for collaboration and code maintenance. Key recommendations include using imperative language, limiting line lengths, and ensuring clarity for future reference. The document also provides specific formatting guidelines and the rationale behind maintaining thorough commit messages.
Commit messages - Good practices
- 1. Commit Messages Good Practices by Tarin Gamberini www.taringamberini.com CC BY-NC-SA 3.0
- 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. 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. Usually Do No t write commit Messages ?!?
- 6. Any software project is a collaborative project Any software project has at least two developers ... Commit Messages Why?
- 7. … the original developer Commit Messages Why? ... the original developer few months later
- 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. … what revision xyz was supposed to do Commit Messages Why?
- 10. Because when some requirement can be implemented several ways in the responsible developer will write, in revision xyz ... Commit Messages Why?
- 11. … why revision xyz was implemented in that way Commit Messages Why?
- 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. … why revision xyz was added Commit Messages Why?
- 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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 ...
- 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. 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. 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