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.

Transcript

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

   View Slide

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

   View Slide

3. @tombruijn
   ☎ * ring ring *
   

   View Slide

4. @tombruijn
   A bug report!
   
   
   
   

   View Slide

5. @tombruijn
   Let's debug!
   
   
   

   View Slide

6. @tombruijn
   

   View Slide

7. @tombruijn
   $ git blame
   

   View Slide

8. @tombruijn
   

   View Slide

9. @tombruijn
   "WIP"
   Author: Dave
   (who no longer works here)
   Date: 2016-04-28 11:49
   

   View Slide

10. @tombruijn
    is about
    communication
    Tom de Bruijn
    Developer @ AppSignal
    

    View Slide

11. @tombruijn
    How does this happen?
    

    View Slide

12. @tombruijn
    

    View Slide

13. @tombruijn
    "WIP"
    Author: Dave
    (who no longer works here)
    Date: 2016-04-28 11:49 Lunch?
    

    View Slide

14. @tombruijn
    git is not simply
    $ git add .
    $ git commit -m "WIP"
    $ git push
    

    View Slide

15. @tombruijn
    Communication
    is important
    

    View Slide

16. @tombruijn
    Development is not
    only typing code.
    
    
    

    View Slide

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

    View Slide

18. @tombruijn
    We do use git blame
    Right?
    

    View Slide

19. @tombruijn
    My code from 3 months ago
    

    View Slide

20. @tombruijn
    * Not be another source of frustration
    git blame
    should help us debug
    

    View Slide

21. @tombruijn
    git is talking to
    Your team
    Yourself, from the future
    

    View Slide

22. @tombruijn
    Bad commits
    

    View Slide

23. @tombruijn
    WTF?
    

    View Slide

24. @tombruijn
    
    
    

    View Slide

25. @tombruijn
    Hall of Shame
    • WIP
    • Fix bug
    • update tests
    • Move method
    • closes #123
    • ...
    

    View Slide

26. @tombruijn
    Extremely unhelpful
    

    View Slide

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

    View Slide

28. @tombruijn
    Making assumptions
    moving forward
    
    

    View Slide

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

    View Slide

30. @tombruijn
    Fixing the bug
    

    View Slide

31. @tombruijn
    * ring ring *
    

    View Slide

32. @tombruijn
    Debug with
    team members
    
    

    View Slide

33. @tombruijn
    Figured it out?
    
    
    

    View Slide

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

    View Slide

35. @tombruijn
    Don't make
    the same mistake!
    git blame our own commits 3 months from now
    

    View Slide

36. @tombruijn
    We learned a lot
    Write it down!
    

    View Slide

37. @tombruijn
    Making better commits
    Adding more content
    

    View Slide

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

    View Slide

39. @tombruijn
    Did you know?
    1 thing to make your commits 1000x more useful
    

    View Slide

40. @tombruijn
    git commit
    supports multiline
    This bad boy can fit so much text in it
    

    View Slide

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

    View Slide

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.
    

    View Slide

43. @tombruijn
    What do we write?
    More on that later
    

    View Slide

44. @tombruijn
    Commits are part of
    the documentation
    

    View Slide

45. @tombruijn
    Other documentation sources
    • README
    • Wiki
    • Guides
    • Inline comments (outdated of course)
    

    View Slide

46. @tombruijn
    Writing
    documentation
    may not be fun
    

    View Slide

47. @tombruijn
    Having no
    documentation
    is much worse
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

52. @tombruijn
    How it could be better
    • git checkout the code
    • Poke around
    • Try to break it
    • Check if the tests actually test things
    

    View Slide

53. @tombruijn
    How do we know
    what the change should do?
    

    View Slide

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

    View Slide

55. @tombruijn
    First we need to ask
    
    

    View Slide

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

    View Slide

57. @tombruijn
    Reviewers need more context
    to review properly
    

    View Slide

58. @tombruijn
    Explain the why
    

    View Slide

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

    View Slide

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

    View Slide

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!!!
    

    View Slide

62. @tombruijn
    A commit format
    

    View Slide

63. @tombruijn
    The scenario
    • Describe the problem that
    occurred
    • Do not only link to a ticket/
    issue
    

    View Slide

64. @tombruijn
    The scenario - Example
    When X happened...
    When error was raised...
    I dreamed about refactoring this...
    

    View Slide

65. @tombruijn
    How the problem was solved
    • What does this solution do?
    • Why this solution?
    

    View Slide

66. @tombruijn
    How the problem was solved - Example
    Initialize class first to fix
    method call
    

    View Slide

67. @tombruijn
    Alternatives
    • Why not other solutions?
    • Why is solution better?
    

    View Slide

68. @tombruijn
    Alternatives - Example
    I consider Y but...
    Doing Y instead didn't work because...
    

    View Slide

69. @tombruijn
    Cite your sources!
    

    View Slide

70. @tombruijn
    Finally:
    A subject summarizing
    the changes
    

    View Slide

71. @tombruijn
    WIP
    

    View Slide

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

    View Slide

73. @tombruijn
    Making it easier to review
    

    View Slide

74. @tombruijn
    Pull Request
    with 1 commit
    

    View Slide

75. @tombruijn
    Pull Request
    with multiple commits
    

    View Slide

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

    View Slide

77. @tombruijn
    Make small Pull Requests
    and small commits
    

    View Slide

78. @tombruijn
    vs
    PR #123 PR #256
    

    View Slide

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

    View Slide

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

    View Slide

81. @tombruijn
    Break large Pull Requests
    into smaller ones
    Unrelated bug fixes, refactorings, etc
    

    View Slide

82. @tombruijn
    Present a tidy history
    

    View Slide

83. @tombruijn
    Development history
    • WIP
    • Add button to edit user profile
    • Merge remote-tracking branch
    'origin/develop'
    • Refactor button component
    • Fix tests
    ?
    ?
    ?
    ?
    ? ✅
    ✅
    

    View Slide

84. @tombruijn
    ❌ "WIP" commits
    ❌ Merge commits
    ❌ "Fix tests" commits
    

    View Slide

85. @tombruijn
    

    View Slide

86. @tombruijn
    A little rebasing
    
    
    

    View Slide

87. @tombruijn
    • WIP
    • Add button to edit user profile
    • Merge remote-tracking branch
    'origin/develop'
    • Refactor button component
    • Fix tests
    

    View Slide

88. @tombruijn
    $ git rebase --interactive develop
    

    View Slide

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
    

    View Slide

90. @tombruijn
    Tidy history
    • Refactor button component
    • Add button to edit user profile
    

    View Slide

91. @tombruijn
    Tidy history
    • Add button to edit user profile
    • Refactor button component
    • I now implemented the button twice
    

    View Slide

92. @tombruijn
    What did we learn?
    

    View Slide

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

    View Slide

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
    
    

    View Slide

95. @tombruijn
    ✅ Better reviews
    ✅ Faster reviews
    ✅ Faster debugging
    

    View Slide

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

    View Slide

97. @tombruijn
    In written form
    tomdebruijn.com/posts/git-is-about-communication
    

    View Slide

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

    View Slide