Git is about communication

@tombruijn How to pilot your ﬁrst Gundam Tom de Bruijn
Aspiring Gundam pilot

@tombruijn Step 1: Get in the damn robot!

@tombruijn ☎ * ring ring *

@tombruijn A bug report!

@tombruijn Let's debug!

@tombruijn

@tombruijn $ git blame

@tombruijn

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

@tombruijn is about communication Tom de Bruijn Developer @ AppSignal

@tombruijn How does this happen?

@tombruijn

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

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

@tombruijn Communication is important

@tombruijn Development is not only typing code.

@tombruijn A bad git blame is a breakdown of communication

@tombruijn We do use git blame Right?

@tombruijn My code from 3 months ago

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

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

@tombruijn Bad commits

@tombruijn WTF?

@tombruijn

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

@tombruijn Extremely unhelpful

@tombruijn These commits don't tell us anything

@tombruijn Making assumptions moving forward

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

@tombruijn Fixing the bug

@tombruijn * ring ring *

@tombruijn Debug with team members

@tombruijn Figured it out?

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

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

@tombruijn We learned a lot Write it down!

@tombruijn Making better commits Adding more content

@tombruijn $ git commit -m "Fix bug"

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

@tombruijn git commit supports multiline This bad boy can ﬁt
so much text in it

@tombruijn $ git commit -m "Fix bug"

@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.

@tombruijn What do we write? More on that later

@tombruijn Commits are part of the documentation

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

@tombruijn Writing documentation may not be fun

@tombruijn Having no documentation is much worse

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

@tombruijn Anyone can write docs We'll ﬁgure it out together

@tombruijn Reviewing Pull Requests Putting on our reviewer hats

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

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

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

@tombruijn Now is the time to ask questions!

@tombruijn First we need to ask

@tombruijn How can we make this even better?

@tombruijn Reviewers need more context to review properly

@tombruijn Explain the why

@tombruijn We shouldn't have to assume things

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

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

@tombruijn A commit format

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

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

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

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

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

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

@tombruijn Cite your sources!

@tombruijn Finally: A subject summarizing the changes

@tombruijn WIP

@tombruijn More is better Write a novel! EXAMPLE

@tombruijn Making it easier to review

@tombruijn Pull Request with 1 commit

@tombruijn Pull Request with multiple commits

@tombruijn Pull Requests should only have content from commits

@tombruijn Make small Pull Requests and small commits

@tombruijn vs PR #123 PR #256

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

@tombruijn ✅ One change ✅ One context Easier to review

@tombruijn Break large Pull Requests into smaller ones Unrelated bug
ﬁxes, refactorings, etc

@tombruijn Present a tidy history

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

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

@tombruijn

@tombruijn A little rebasing

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

@tombruijn $ git rebase --interactive develop

@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

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

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

@tombruijn What did we learn?

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

@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

@tombruijn ✅ Better reviews ✅ Faster reviews ✅ Faster debugging

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

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

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

Git is about communication

Git is about communication

More Decks by Tom de Bruijn

Other Decks in Programming

Featured

Transcript