@tombruijn
How to pilot your first Gundam
Tom de Bruijn
Aspiring Gundam pilot
Slide 2
Slide 2 text
@tombruijn
Step 1:
Get in the damn robot!
Slide 3
Slide 3 text
@tombruijn
☎ * ring ring *
Slide 4
Slide 4 text
@tombruijn
A bug report!
Slide 5
Slide 5 text
@tombruijn
Let's debug!
Slide 6
Slide 6 text
@tombruijn
Slide 7
Slide 7 text
@tombruijn
$ git blame
Slide 8
Slide 8 text
@tombruijn
Slide 9
Slide 9 text
@tombruijn
"WIP"
Author: Dave
(who no longer works here)
Date: 2016-04-28 11:49
Slide 10
Slide 10 text
@tombruijn
is about
communication
Tom de Bruijn
Developer @ AppSignal
Slide 11
Slide 11 text
@tombruijn
How does this happen?
Slide 12
Slide 12 text
@tombruijn
Slide 13
Slide 13 text
@tombruijn
"WIP"
Author: Dave
(who no longer works here)
Date: 2016-04-28 11:49 Lunch?
Slide 14
Slide 14 text
@tombruijn
git is not simply
$ git add .
$ git commit -m "WIP"
$ git push
Slide 15
Slide 15 text
@tombruijn
Communication
is important
Slide 16
Slide 16 text
@tombruijn
Development is not
only typing code.
Slide 17
Slide 17 text
@tombruijn
A bad git blame
is a breakdown of
communication
Slide 18
Slide 18 text
@tombruijn
We do use git blame
Right?
Slide 19
Slide 19 text
@tombruijn
My code from 3 months ago
Slide 20
Slide 20 text
@tombruijn
* Not be another source of frustration
git blame
should help us debug
Slide 21
Slide 21 text
@tombruijn
git is talking to
Your team
Yourself, from the future
Slide 22
Slide 22 text
@tombruijn
Bad commits
Slide 23
Slide 23 text
@tombruijn
WTF?
Slide 24
Slide 24 text
@tombruijn
Slide 25
Slide 25 text
@tombruijn
Hall of Shame
• WIP
• Fix bug
• update tests
• Move method
• closes #123
• ...
Slide 26
Slide 26 text
@tombruijn
Extremely unhelpful
Slide 27
Slide 27 text
@tombruijn
These commits
don't tell us anything
Slide 28
Slide 28 text
@tombruijn
Making assumptions
moving forward
Slide 29
Slide 29 text
@tombruijn
Ask the author?
Sick, vacation, left the company
Slide 30
Slide 30 text
@tombruijn
Fixing the bug
Slide 31
Slide 31 text
@tombruijn
* ring ring *
Slide 32
Slide 32 text
@tombruijn
Debug with
team members
Slide 33
Slide 33 text
@tombruijn
Figured it out?
Slide 34
Slide 34 text
@tombruijn
$ git commit -m "Fix bug" ?
Slide 35
Slide 35 text
@tombruijn
Don't make
the same mistake!
git blame our own commits 3 months from now
Slide 36
Slide 36 text
@tombruijn
We learned a lot
Write it down!
Slide 37
Slide 37 text
@tombruijn
Making better commits
Adding more content
Slide 38
Slide 38 text
@tombruijn
$ git commit -m "Fix bug"
Slide 39
Slide 39 text
@tombruijn
Did you know?
1 thing to make your commits 1000x more useful
Slide 40
Slide 40 text
@tombruijn
git commit
supports multiline
This bad boy can fit so much text in it
Slide 41
Slide 41 text
@tombruijn
$ git commit -m "Fix bug"
Slide 42
Slide 42 text
@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.
Slide 43
Slide 43 text
@tombruijn
What do we write?
More on that later
Slide 44
Slide 44 text
@tombruijn
Commits are part of
the documentation
Slide 45
Slide 45 text
@tombruijn
Other documentation sources
• README
• Wiki
• Guides
• Inline comments (outdated of course)
Slide 46
Slide 46 text
@tombruijn
Writing
documentation
may not be fun
Slide 47
Slide 47 text
@tombruijn
Having no
documentation
is much worse
Slide 48
Slide 48 text
@tombruijn
Documentation is for people
not in the room
Room/office/team/call/meeting/company/etc.
Slide 49
Slide 49 text
@tombruijn
Anyone can write docs
We'll figure it out together
Slide 50
Slide 50 text
@tombruijn
Reviewing Pull Requests
Putting on our reviewer hats
Slide 51
Slide 51 text
@tombruijn
What's a good review?
Does the code look ok?
Slide 52
Slide 52 text
@tombruijn
How it could be better
• git checkout the code
• Poke around
• Try to break it
• Check if the tests actually test things
Slide 53
Slide 53 text
@tombruijn
How do we know
what the change should do?
Slide 54
Slide 54 text
@tombruijn
Now is the time
to ask questions!
Slide 55
Slide 55 text
@tombruijn
First we need to ask
Slide 56
Slide 56 text
@tombruijn
How can we make this
even better?
Slide 57
Slide 57 text
@tombruijn
Reviewers need more context
to review properly
Slide 58
Slide 58 text
@tombruijn
Explain the why
Slide 59
Slide 59 text
@tombruijn
We shouldn't have to
assume things
Slide 60
Slide 60 text
@tombruijn
git blame
should be
git why
git config --global alias.why blame
Slide 61
Slide 61 text
@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!!!
Slide 62
Slide 62 text
@tombruijn
A commit format
Slide 63
Slide 63 text
@tombruijn
The scenario
• Describe the problem that
occurred
• Do not only link to a ticket/
issue
Slide 64
Slide 64 text
@tombruijn
The scenario - Example
When X happened...
When error was raised...
I dreamed about refactoring this...
Slide 65
Slide 65 text
@tombruijn
How the problem was solved
• What does this solution do?
• Why this solution?
Slide 66
Slide 66 text
@tombruijn
How the problem was solved - Example
Initialize class first to fix
method call
Slide 67
Slide 67 text
@tombruijn
Alternatives
• Why not other solutions?
• Why is solution better?
Slide 68
Slide 68 text
@tombruijn
Alternatives - Example
I consider Y but...
Doing Y instead didn't work because...
Slide 69
Slide 69 text
@tombruijn
Cite your sources!
Slide 70
Slide 70 text
@tombruijn
Finally:
A subject summarizing
the changes
Slide 71
Slide 71 text
@tombruijn
WIP
Slide 72
Slide 72 text
@tombruijn
More is better
Write a novel!
EXAMPLE
Slide 73
Slide 73 text
@tombruijn
Making it easier to review
Slide 74
Slide 74 text
@tombruijn
Pull Request
with 1 commit
Slide 75
Slide 75 text
@tombruijn
Pull Request
with multiple commits
Slide 76
Slide 76 text
@tombruijn
Pull Requests should only
have content from commits
Slide 77
Slide 77 text
@tombruijn
Make small Pull Requests
and small commits
Slide 78
Slide 78 text
@tombruijn
vs
PR #123 PR #256
Slide 79
Slide 79 text
@tombruijn
❌ Too many changes
❌ Too much context
Difficult to review
Slide 80
Slide 80 text
@tombruijn
✅ One change
✅ One context
Easier to review
Slide 81
Slide 81 text
@tombruijn
Break large Pull Requests
into smaller ones
Unrelated bug fixes, refactorings, etc
Slide 82
Slide 82 text
@tombruijn
Present a tidy history
Slide 83
Slide 83 text
@tombruijn
Development history
• WIP
• Add button to edit user profile
• Merge remote-tracking branch
'origin/develop'
• Refactor button component
• Fix tests
?
?
?
?
? ✅
✅
@tombruijn
Tidy history
• Refactor button component
• Add button to edit user profile
Slide 91
Slide 91 text
@tombruijn
Tidy history
• Add button to edit user profile
• Refactor button component
• I now implemented the button twice
Slide 92
Slide 92 text
@tombruijn
What did we learn?
Slide 93
Slide 93 text
@tombruijn
• We do this for our team
• We do this for our future selves
Slide 94
Slide 94 text
@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