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 full-size slide

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

    View full-size slide

  3. @tombruijn
    ☎ * ring ring *

    View full-size slide

  4. @tombruijn
    A bug report!



    View full-size slide

  5. @tombruijn
    Let's debug!


    View full-size slide

  6. @tombruijn
    $ git blame

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  9. @tombruijn
    How does this happen?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  12. @tombruijn
    Communication
    is important

    View full-size slide

  13. @tombruijn
    Development is not
    only typing code.


    View full-size slide

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

    View full-size slide

  15. @tombruijn
    We do use git blame
    Right?

    View full-size slide

  16. @tombruijn
    My code from 3 months ago

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  19. @tombruijn
    Bad commits

    View full-size slide

  20. @tombruijn
    WTF?

    View full-size slide

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

    View full-size slide

  22. @tombruijn
    Extremely unhelpful

    View full-size slide

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

    View full-size slide

  24. @tombruijn
    Making assumptions
    moving forward

    View full-size slide

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

    View full-size slide

  26. @tombruijn
    Fixing the bug

    View full-size slide

  27. @tombruijn
    * ring ring *

    View full-size slide

  28. @tombruijn
    Debug with
    team members

    View full-size slide

  29. @tombruijn
    Figured it out?


    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  33. @tombruijn
    Making better commits
    Adding more content

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  38. @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 full-size slide

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

    View full-size slide

  40. @tombruijn
    Commits are part of
    the documentation

    View full-size slide

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

    View full-size slide

  42. @tombruijn
    Writing
    documentation
    may not be fun

    View full-size slide

  43. @tombruijn
    Having no
    documentation
    is much worse

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  51. @tombruijn
    First we need to ask

    View full-size slide

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

    View full-size slide

  53. @tombruijn
    Reviewers need more context
    to review properly

    View full-size slide

  54. @tombruijn
    Explain the why

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  57. @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 full-size slide

  58. @tombruijn
    A commit format

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  65. @tombruijn
    Cite your sources!

    View full-size slide

  66. @tombruijn
    Finally:
    A subject summarizing
    the changes

    View full-size slide

  67. @tombruijn
    WIP

    View full-size slide

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

    View full-size slide

  69. @tombruijn
    Making it easier to review

    View full-size slide

  70. @tombruijn
    Pull Request
    with 1 commit

    View full-size slide

  71. @tombruijn
    Pull Request
    with multiple commits

    View full-size slide

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

    View full-size slide

  73. @tombruijn
    Make small Pull Requests
    and small commits

    View full-size slide

  74. @tombruijn
    vs
    PR #123 PR #256

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  78. @tombruijn
    Present a tidy history

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  81. @tombruijn
    A little rebasing


    View full-size slide

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

    View full-size slide

  83. @tombruijn
    $ git rebase --interactive develop

    View full-size slide

  84. @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 full-size slide

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

    View full-size slide

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

    View full-size slide

  87. @tombruijn
    What did we learn?

    View full-size slide

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

    View full-size slide

  89. @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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide