A place to cache linked articles (think custom and personal wayback machine)
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

index.md 15KB

il y a 4 ans
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271
  1. title: Telling stories through your commits
  2. url: https://blog.mocoso.co.uk/talks/2015/01/12/telling-stories-through-your-commits/
  3. hash_url: 13d9da5621e5616aee2248696390c693
  4. <p>This is a short talk that I have given on a variety of occasions about
  5. how you can use your source control commit messages to keep track of the
  6. intent of your code changes and make it easier to keep changing your
  7. project in future.</p>
  8. <p>The transcript below is from the version of the talk that I gave at the
  9. <a href="http://2016.theleaddeveloper.com/talks#joel-chippindale">Lead Developer
  10. Conference</a> in
  11. London in June 2016.</p>
  12. <h2 id="transcript">Transcript</h2>
  13. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.001.png" alt="opening slide"/></p>
  14. <p class="transcript">I am Joel Chippindale and I have been the CTO at FutureLearn for the
  15. last few years and I am here to talk to you about telling stories
  16. through your commits.</p>
  17. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.002.png" alt="opening slide"/></p>
  18. <p class="transcript">If we have a successful software development project then our key
  19. challenge, as lead developers, is to manage complexity because projects
  20. can get very complex very quickly even within quite small teams.</p>
  21. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.003.png" alt="opening slide"/></p>
  22. <p class="transcript">As lead developers we, and our teams, spend a lot of time thinking about
  23. this. We think about the naming of methods and functions and variables
  24. and…</p>
  25. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.004.png" alt="opening slide"/></p>
  26. <p class="transcript">we think about our code design.</p>
  27. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.005.png" alt="opening slide"/></p>
  28. <p class="transcript">We probably spend a lot of time refactoring code. Taking code that works
  29. and making it simpler to understand.</p>
  30. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.006.png" alt="opening slide"/></p>
  31. <p class="transcript">And probably most of your teams are spending a good proportion of their
  32. time writing automated tests and that allows your teams to have the
  33. confidence to keep changing the software but also helps to document what
  34. the code is supposed to do.</p>
  35. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.007.png" alt="opening slide"/></p>
  36. <p class="transcript">All these tools and techniques help communicate the intent of our
  37. software and if we want to keep changing it we need to understand this
  38. intent.</p>
  39. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.008.png" alt="opening slide"/></p>
  40. <p class="transcript">There is one tool that we under utilise in our communities for
  41. communicating our intent and that is our version control system. All the
  42. examples in this talk use git but the principles apply to whatever
  43. system you are using.</p>
  44. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.009.png" alt="opening slide"/></p>
  45. <p class="transcript">Our commit history has some very special properties which make it
  46. particularly useful for documenting intent.</p>
  47. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.010.png" alt="opening slide"/></p>
  48. <p class="transcript">It is kept forever.</p>
  49. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.011.png" alt="opening slide"/></p>
  50. <p class="transcript">It is always up to date and this almost certainly not true of most of
  51. the documentation you have, perhaps in a wiki or even in code comments.</p>
  52. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.012.png" alt="opening slide"/></p>
  53. <p class="transcript">And, this may come as a surprise to some of you, it is searchable. Git
  54. doesn’t make this obvious so here are some commands that you may find
  55. useful.</p>
  56. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.013.png" alt="opening slide"/></p>
  57. <p class="transcript">You can search all the contents of all your commit messages.</p>
  58. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.014.png" alt="opening slide"/></p>
  59. <p class="transcript">You can search all the contents of all the code changes in your commits.</p>
  60. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.015.png" alt="opening slide"/></p>
  61. <p class="transcript">And you can find out where each line of code was last changed…</p>
  62. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.016.png" alt="opening slide"/></p>
  63. <p class="transcript">…giving you output like this.</p>
  64. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.017.png" alt="opening slide"/></p>
  65. <p class="transcript">It is these properties that allow Mislav Marahonić to say that, “Every
  66. line of code is always documented”. If every line of code is documented
  67. how do we make sure that this documentation tells a useful story to us
  68. and our teams about that line of code?</p>
  69. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.018.png" alt="opening slide"/></p>
  70. <p class="transcript">I will share 3 principles with that will help you with this.</p>
  71. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.019.png" alt="opening slide"/></p>
  72. <p class="transcript">Firstly and most importantly make atomic commits. Make your commits
  73. about a single change to your code base.</p>
  74. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.020.png" alt="opening slide"/></p>
  75. <p class="transcript">To illustrate why this is important I am going to share a git horror
  76. story with you. This is from a project which I am responsible for. Bug
  77. fixes? Which ones? How many? We have no idea. And a Wordpress update.
  78. Those of you who are laughing are probably doing so because there are
  79. 175 thousand lines of code changes in this commit. Reverse engineering
  80. this commit to find out what happened is very hard.</p>
  81. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.021.png" alt="opening slide"/></p>
  82. <p class="transcript">Let us imagine an alternate history where this commit had been split
  83. into atomic commits.</p>
  84. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.022.png" alt="opening slide"/></p>
  85. <p class="transcript">Here we might have a Wordpress update commit containing the vast
  86. majority of those 175k lines of changes and then 8 separate commits each
  87. one about a single bug which is easy to understand.</p>
  88. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.023.png" alt="opening slide"/></p>
  89. <p class="transcript">When I talk about this, I am often asked how big an atomic commit should
  90. be? In our industry we generally make our commits too big so it is worth
  91. thinking about a minimum viable commit. What’s the smallest useful
  92. change that you can make to your codebase?</p>
  93. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.024.png" alt="opening slide"/></p>
  94. <p class="transcript">Another useful rule of thumb is to avoid needing ‘and’ in your commit
  95. messages. If you did ‘A’ and ‘B’ maybe they are two separate changes.</p>
  96. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.025.png" alt="opening slide"/></p>
  97. <p class="transcript">Second principle: write good commit messages.</p>
  98. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.026.png" alt="opening slide"/></p>
  99. <p class="transcript">That’s very easy for me to say so I will take you through a template to
  100. give you more of an idea of what I mean.</p>
  101. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.027.png" alt="opening slide"/></p>
  102. <p class="transcript">Short one line title because you view your commits in lists and a longer
  103. description if you need it.</p>
  104. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.028.png" alt="opening slide"/></p>
  105. <p class="transcript">An explanation of why the change is being made. If people want to know
  106. how they can change this in future then they need to know what the
  107. intention of this change was.</p>
  108. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.029.png" alt="opening slide"/></p>
  109. <p class="transcript">Lastly, when you make this commit, you know more about why you are
  110. making this change and how you are fixing or improving this thing than
  111. anyone else ever will and so it can be useful to outline some of the
  112. context and alternative approaches considered.</p>
  113. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.030.png" alt="opening slide"/></p>
  114. <p class="transcript">To make this more concrete, here is an example of a commit message from
  115. one of the other projects I am responsible for. You can see the one line
  116. title, you can see a link to our bug tracking system, you can see an
  117. explanation of the quirks of Outlook and why we are making this
  118. particular change and a link to a blog post which explains more about
  119. the problem. This is gold dust for people going back and trying to work
  120. out why the CSS in our project is in the particular state it is in.</p>
  121. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.031.png" alt="opening slide"/></p>
  122. <p class="transcript">Third principle: revise your development history before sharing. We all
  123. know that once commits are on master, or once they are deployed, you
  124. don’t want to change them out from underneath people. But, in your
  125. development branches, it can be much more useful if they tell a story
  126. about what you intended to do instead of a blow by blow account of all
  127. the missteps you took along the way.</p>
  128. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.032.png" alt="opening slide"/></p>
  129. <p class="transcript">There’s a tool for this, git rebase interactive…</p>
  130. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.033.png" alt="opening slide"/></p>
  131. <p class="transcript">…and this allows you to remove, reorder, edit, merge and split
  132. commits. Essentially with this tool your development branches are
  133. infinitely malleable.</p>
  134. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.034.png" alt="opening slide"/></p>
  135. <p class="transcript">To give you a quick example. Imagine I have added Foo and made a commit,
  136. removed Bar and made a commit and then I have spotted a typo in the
  137. first commit so I make a new commit to fix the typo. That’s just noise
  138. for other people. No one cares about the fact that I didn’t get the
  139. first commit right first time.</p>
  140. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.035.png" alt="opening slide"/></p>
  141. <p class="transcript">We can use git rebase interactive to merge the first and third commits
  142. and tell a simpler story about what we are trying to do.</p>
  143. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.036.png" alt="opening slide"/></p>
  144. <p class="transcript">So three principles. 1. Make atomic commits. 2. Write good commit
  145. messages and 3. Revise your development history before sharing</p>
  146. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.037.png" alt="opening slide"/></p>
  147. <p class="transcript">This is a quote from someone who joined our team recently which I hope
  148. will help persuade you of the benefits of taking this approach.</p>
  149. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.038.png" alt="opening slide"/></p>
  150. <p class="transcript">Perhaps you are sitting here, as lead developers, thinking this sounds
  151. like a really good idea. How am I going to take this back to my team on
  152. Monday? How am I going to persuade them to adopt these practices that
  153. seem like they have pay off months or even years down the line perhaps
  154. for other developers on the team?</p>
  155. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.039.png" alt="opening slide"/></p>
  156. <p class="transcript">Won’t it take a huge amount of discipline?</p>
  157. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.040.png" alt="opening slide"/></p>
  158. <p class="transcript">I think the key is that all these practices make things simpler for
  159. individual developers in your team right now.</p>
  160. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.041.png" alt="opening slide"/></p>
  161. <div class="transcript">
  162. <p>Let’s go back over the principles.</p>
  163. <p><strong>Make atomic commits</strong></p>
  164. <p>This is about making sure that you are making one change at a time to
  165. your code. This makes it simpler to work on.</p>
  166. <p><strong>Write good commit messages</strong></p>
  167. <p>If you can write down what you are trying to do in the particular change
  168. that you are making then you are half way there already and it is a
  169. really valuable discipline for you and your teams to get into.</p>
  170. <p><strong>Revise your history before sharing</strong></p>
  171. <p>If your development branch tells a good story about what you did then it
  172. is easier for you to understand what you did and whether it solves the
  173. problem you had and also it is easier to share with others, perhaps in a
  174. pull request, to get feedback. All these practices making things easier
  175. now for your teams.</p>
  176. </div>
  177. <p class="slide"><img src="https://blog.mocoso.co.uk/assets/telling-stories-through-your-commits/slides.042.png" alt="opening slide"/></p>
  178. <p class="transcript">Thank you for your time.</p>