Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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
Tweet

More Decks by Tom de Bruijn

Other Decks in Programming

Transcript

  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

    future
  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"

    commits
  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 tomdebruijn.com/posts/git-is-about-communication

  98. @tombruijn Thanks for listening! tomdebruijn.com/posts/git-is-about-communication git better together!