Git is about communication

Git is about communication

Git is a way to communicate with your team. Well written commits and Pull Requests ensure that this communication goes smoothly.

Document why you made a change in your git commits. Your team, your future self, and your future colleague will thank you.


Tom de Bruijn

August 21, 2020


  1. @tombruijn How to pilot your first Gundam Tom de Bruijn

    Aspiring Gundam pilot
  2. @tombruijn Step 1: Get in the damn robot!

  3. @tombruijn ☎ * ring ring *

  4. @tombruijn A bug report!

  5. @tombruijn Let's debug!

  6. @tombruijn

  7. @tombruijn $ git blame

  8. @tombruijn

  9. @tombruijn "WIP" Author: Dave (who no longer works here) Date:

    2016-04-28 11:49
  10. @tombruijn is about communication Tom de Bruijn Developer @ AppSignal

  11. @tombruijn How does this happen?

  12. @tombruijn

  13. @tombruijn "WIP" Author: Dave (who no longer works here) Date:

    2016-04-28 11:49 Lunch?
  14. @tombruijn git is not simply $ git add . $

    git commit -m "WIP" $ git push
  15. @tombruijn Communication is important

  16. @tombruijn Development is not only typing code.

  17. @tombruijn A bad git blame is a breakdown of communication

  18. @tombruijn We do use git blame Right?

  19. @tombruijn My code from 3 months ago

  20. @tombruijn * Not be another source of frustration git blame

    should help us debug
  21. @tombruijn git is talking to Your team Yourself, from the

  22. @tombruijn Bad commits

  23. @tombruijn WTF?

  24. @tombruijn

  25. @tombruijn Hall of Shame • WIP • Fix bug •

    update tests • Move method • closes #123 • ...
  26. @tombruijn Extremely unhelpful

  27. @tombruijn These commits don't tell us anything

  28. @tombruijn Making assumptions moving forward

  29. @tombruijn Ask the author? Sick, vacation, left the company

  30. @tombruijn Fixing the bug

  31. @tombruijn * ring ring *

  32. @tombruijn Debug with team members

  33. @tombruijn Figured it out?

  34. @tombruijn $ git commit -m "Fix bug" ?

  35. @tombruijn Don't make the same mistake! git blame our own

    commits 3 months from now
  36. @tombruijn We learned a lot Write it down!

  37. @tombruijn Making better commits Adding more content

  38. @tombruijn $ git commit -m "Fix bug"

  39. @tombruijn Did you know? 1 thing to make your commits

    1000x more useful
  40. @tombruijn git commit supports multiline This bad boy can fit

    so much text in it
  41. @tombruijn $ git commit -m "Fix bug"

  42. @tombruijn This is a commit subject This is a commit

    message that can be much longer than the subject. Here we can explain the change in more detail than we could in the subject of the commit.
  43. @tombruijn What do we write? More on that later

  44. @tombruijn Commits are part of the documentation

  45. @tombruijn Other documentation sources • README • Wiki • Guides

    • Inline comments (outdated of course)
  46. @tombruijn Writing documentation may not be fun

  47. @tombruijn Having no documentation is much worse

  48. @tombruijn Documentation is for people not in the room Room/office/team/call/meeting/company/etc.

  49. @tombruijn Anyone can write docs We'll figure it out together

  50. @tombruijn Reviewing Pull Requests Putting on our reviewer hats

  51. @tombruijn What's a good review? Does the code look ok?

  52. @tombruijn How it could be better • git checkout the

    code • Poke around • Try to break it • Check if the tests actually test things
  53. @tombruijn How do we know what the change should do?

  54. @tombruijn Now is the time to ask questions!

  55. @tombruijn First we need to ask

  56. @tombruijn How can we make this even better?

  57. @tombruijn Reviewers need more context to review properly

  58. @tombruijn Explain the why

  59. @tombruijn We shouldn't have to assume things

  60. @tombruijn git blame should be git why git config --global

    alias.why blame
  61. @tombruijn Write down why a change was made Not just

    what was changed That's what the diff is for This is the most important thing!! The MOST important thing!!!
  62. @tombruijn A commit format

  63. @tombruijn The scenario • Describe the problem that occurred •

    Do not only link to a ticket/ issue
  64. @tombruijn The scenario - Example When X happened... When error

    was raised... I dreamed about refactoring this...
  65. @tombruijn How the problem was solved • What does this

    solution do? • Why this solution?
  66. @tombruijn How the problem was solved - Example Initialize class

    first to fix method call
  67. @tombruijn Alternatives • Why not other solutions? • Why is

    solution better?
  68. @tombruijn Alternatives - Example I consider Y but... Doing Y

    instead didn't work because...
  69. @tombruijn Cite your sources!

  70. @tombruijn Finally: A subject summarizing the changes

  71. @tombruijn WIP

  72. @tombruijn More is better Write a novel! EXAMPLE

  73. @tombruijn Making it easier to review

  74. @tombruijn Pull Request with 1 commit

  75. @tombruijn Pull Request with multiple commits

  76. @tombruijn Pull Requests should only have content from commits

  77. @tombruijn Make small Pull Requests and small commits

  78. @tombruijn vs PR #123 PR #256

  79. @tombruijn ❌ Too many changes ❌ Too much context Difficult

    to review
  80. @tombruijn ✅ One change ✅ One context Easier to review

  81. @tombruijn Break large Pull Requests into smaller ones Unrelated bug

    fixes, refactorings, etc
  82. @tombruijn Present a tidy history

  83. @tombruijn Development history • WIP • Add button to edit

    user profile • Merge remote-tracking branch 'origin/develop' • Refactor button component • Fix tests ? ? ? ? ? ✅ ✅
  84. @tombruijn ❌ "WIP" commits ❌ Merge commits ❌ "Fix tests"

  85. @tombruijn

  86. @tombruijn A little rebasing

  87. @tombruijn • WIP • Add button to edit user profile

    • Merge remote-tracking branch 'origin/develop' • Refactor button component • Fix tests
  88. @tombruijn $ git rebase --interactive develop

  89. @tombruijn • pick WIP • fixup Merge remote-tracking branch 'origin/develop'

    • squash Refactor button component • fixup Fix tests • pick Add button to edit user profile • fixup Fix tests
  90. @tombruijn Tidy history • Refactor button component • Add button

    to edit user profile
  91. @tombruijn Tidy history • Add button to edit user profile

    • Refactor button component • I now implemented the button twice
  92. @tombruijn What did we learn?

  93. @tombruijn • We do this for our team • We

    do this for our future selves
  94. @tombruijn • Commits explain • Why this change was made

    • How it was implemented • What alternatives were considered • Why this solution was better • Small Pull Requests • Tidy git history
  95. @tombruijn ✅ Better reviews ✅ Faster reviews ✅ Faster debugging

  96. @tombruijn Your team, your future self, and your future colleagues

    will thank you
  97. @tombruijn In written form

  98. @tombruijn Thanks for listening! git better together!