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

    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