Advertisement
Guest User

Untitled

a guest
Jul 23rd, 2013
877
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 6.91 KB | None | 0 0
  1. What Is a Good Commit Message
  2.  
  3. Commit messages are the most common way developers communicate with other developers.
  4.  
  5. The goal of a commit message is to communicate your change with everybody else.
  6.  
  7. The audience of a commit message is:
  8.  
  9. 0. People reading the commit timeline.
  10.  
  11. 1. People debugging code.
  12.  
  13. Having these assumptions in mind:
  14.  
  15. A good commit message must have a subject line. One sentence-long brief description of what the change and if it makese sense why.
  16.  
  17. A good subject line gives the reader the power to know the gist of the commit without bothering to read the whole commit message.
  18.  
  19. Example:
  20.  
  21. Fix stats link on m.wordpress.com
  22. This does not need a high-level why part, because it’s obvious – the links weren’t working.
  23.  
  24. Example:
  25.  
  26. VIP Report: clear caches on each post to save memory
  27. Here we need a why part, because if the message was only “clear caches on each post”, I would have to look at the code and then I would be, like, are you crazy? Why the hell would you clear cache for each post in a loop?
  28.  
  29. Whenever the commit is a part of a clearly-defined and named project, prefixing the commit with the project name is very helpful. It’s not mandatory, because often the project space is vague and the list of committed files reveals similar information.
  30.  
  31. There must be an empty line between the subject line and the rest of the commit message (if any). Whitespace is like bacon for our brains.
  32.  
  33. A good commit message tells why a change was made.
  34.  
  35. Reasoning why is helpful to both of our audiences. Those following the timeline, can learn a new approach and how to make their code better. Those tracing bugs gain insight for the context of the problem you were trying to solve and helps them decide whether the root cause is in the implementation or higher up the chain.
  36.  
  37. Explaining why is tricky, because it’s often obvious. “I’m fixing it because it’s broken”. “I’m improving this, because can be better.”
  38.  
  39. If it’s obvious, go one level deeper. The 5 Whys technique is great. Not only for looking for root causes of problems. But for making sure you are doing what you are doing for the right reasons.
  40.  
  41. Example:
  42.  
  43. JSON API: Split class into hierarchy for easier inclusion in Jetpack
  44.  
  45. Including the old code required a bunch of hacks and compatibility layers.
  46. With the new hierarchy, we can get rid of almost all the hacks and drop in
  47. the files to Jetpack as is.
  48. Here the commit message very conveniently explains what were the downsides of the old approach and why the new approach is better.
  49.  
  50. Example:
  51.  
  52. Remove filtering by ticket
  53.  
  54. It's not very useful, while it's slow to generate.
  55.  
  56. The workflow is to usually go to the ticket page and see associated
  57. comments there.
  58. Here the commit message shares a UX decision we made, which is the primary reason of the commit.
  59.  
  60. Most of the commits fix a problem. In this case a good commit message explains what caused the problem and what were its consequences.
  61.  
  62. Everybody needs to know what caused a problem in order to avoid causing a similar problem again. Knowing the consequences can explain already noticed erroneous behaviour and can help somebody debugging a problem compare the consequences of this, already fixed, problem with the one being debugged.
  63.  
  64. If possible, avoid the word fix. Almost always there is a more specific verb for your action.
  65.  
  66. Example:
  67.  
  68. Set the right dropdown values when I enter baba.mlblogs.com in the signup
  69.  
  70. The code, which does the smartness of setting the right dropdown values
  71. wasn't that smart and if I entered baba.mlblogs.com it set the blogname
  72. to baba.mlblogs and the domain to .com, because .com was in front of
  73. .mblogs.com in the list of domains.
  74.  
  75. The solution was to sort the domains by length, this way there is no
  76. chance a domain, which is a suffix of another one will be first in the
  77. list.
  78. We could’ve just fixed the signup dropdown. Instead we set the right values in a specific corner case.
  79.  
  80. Also, we explain what sort of smart code caused the problem. And give an example where the code broke.
  81.  
  82. In the end, we even explain how the fix works (see the “how” rule below).
  83.  
  84. Example:
  85.  
  86. Fix stats link on m.wordpress.com
  87.  
  88. We need double quotes, when we want to use variables in the string.
  89.  
  90. The problem was introduced in the mass sanitization of [46532].
  91. Here we tried, but couldn’t find a better substitute for “fix”. It’s fine.
  92.  
  93. If the problem is caused by a single changeset, a good commit message will mention it.
  94.  
  95. A good commit message explains how it achieves its goal. But only if it isn’t obvious.
  96.  
  97. Most of the time it’s obvious. Only sometimes some high-level algorithm is encoded in the change and it would benefit the reader to know it.
  98.  
  99. Example:
  100.  
  101. Add a first pass client stat for bandwidth
  102.  
  103. Bandwidth is extrapolated from a month sample. From
  104. there we get the average number of bytes per paegview
  105. for each blog. This data is cached in means.json.
  106.  
  107. All the code for generating the data in means.json is
  108. in the static methods of the class.
  109. Here we explain the algorithm for guessing bandwidth data. It would have been possible to extract this information from the commit, but it would’ve taken a lot of time and energy. Also, by including it in the commit message we imply that it’s important for you to know that.
  110.  
  111. Also, see the first example of the previous rule.
  112.  
  113. If the subject line of a commit message contains the word and or in other way lists more than one item, the commit is probably too large. Split it.
  114.  
  115. Make your commits as small as possible. If you notice a coding style problem while fixing a bug, make a note and fix it after you fix the bug. If you are fixing a bug and you notice another bug, make a note and fix the second bug in another commit.
  116.  
  117. The same is especially true for white space changes to existing code. White spaces changes should be a separate commit.
  118.  
  119. A good commit message should not depend on the code to explain what it does or why it does it.
  120.  
  121. Two notes here:
  122.  
  123. This doesn’t mean we should tell what each line of code does. It means that we should convey all the non-trivial information in the code to the commit message.
  124.  
  125. This doesn’t mean we whouldn’t include any of this information in the code. Knowing why a function exists, what it does, or what algorithm does it use can often be a useful comment.
  126.  
  127. A good commit message doesn’t substitute information about what it does or why it does it with a link.
  128.  
  129. Links are encouraged for more context. But a good commit message has a sentence of explanation, not a link to a 20-comments discussion without a clearly extracted conclusion.
  130.  
  131. It’s perfectly OK to spend more time crafting your commit message than writing the code for your commit.
  132.  
  133. It’s perfectly OK for your commit message to be longer than your commit.
  134.  
  135. A good commit message gives props and references relevant Trac tickets.
  136.  
  137. Common sense always overrules what a good commit message thinks it should be.
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement