loading...

Improve Pull Requests with 5 Habits

chantastic profile image Michael Chan ใƒป2 min read

1. Start your message with a verb

Spelunking git history is always a chore.
You can make that chore easier with clear, strong messages.
Start with the verb.
Keep it short.

Fix e2e login spec
Add inactive person styling
Remove presence validation from age on Person model
Decrease TTI on dashboard by 10%


2. Write messages in an imperative style

- Fixed nav jitter
+ Fix nav jitter
- Added CTAButton
+ Add CTAButton

Read 'Should I use past or present tense in git commits message' on stack overflow


3. Use have/need/get to describe your PR

Break you description into 3 logical sections:
Past (have), present (need), and future (get).

Have

Describe what exists.
Demonstrate empathy for the code, team, and constraints that created it.
Don't shit on the past.

Need

Describe the human need.
This is the value that customers get.
Don't jump into technical details yet.
You can probably copy/pasting this from Trello/Jira.

Get

You can't always get what you want

Mick Jagger's right.
Describe your solution in technical terms.
Admit where it falls short.
Point out areas where you don't have enough information to make a better solution.

Bonus: Reference

Link supporting pages, documents, and verbal instructions that helped form your solution.
Give credit to co-workers that helped you.
This gives reviewers insight into your process and improves your credibility.


4. Use the --fixup flag to commit fixes

Once a review starts, useless messages like fix, oops, shit... start piling in.
Use the --fixup flag to make these commits more descriptive.

git commit --fixup a1b2c4

Github has a Confirm squash and merge option that will squash all fixup! commits into the commits they reference.

Read Auto-squashing Git Commits on thoughtbot's blog


5. Check your ego

Remember that you're making a "pull request" โ€” not a "pull demand".
A pull request is the start of a conversation.
Don't assume you got everything right.
Be open to feedback.
You'll probably learn something you didn't know.

Have fun ๐Ÿฅณ
Let me know what you learn ๐Ÿ™Œ

โœ… chantastic

Posted on by:

chantastic profile

Michael Chan

@chantastic

Clumsy Jesus follower. Mediocre dev/designer. Pretty OK hubs and dad.

Discussion

markdown guide
 

Great article ๐Ÿค— especially your last point - remembering that constructive feedback isnโ€™t necessarily a bad thing is super important.

Iโ€™d love to add a few tips of my own:

Tell reviewers how to test your code

When youโ€™re implementing a feature, make sure to tell your reviewers how to test the code thatโ€™s being reviewed. Providing a test environment, a test user, and instructions on how to reach your code helps your peers understand your code better!

Review your own PR

Before I add reviewers to my PR, I go through it myself one last time. If there is any code or choices that warrant a comment or explanation, make sure to add those right away.

Add screenshots!

If youโ€™re creating some sort of UI, make sure to add screenshots or gifs of the UI in question. This helps the reviewers visualize your change quicker!

 

excellent additions ๐Ÿ™Œ

i agree with these 100%
in fact, I actually cut two of them out to get down to five!
decided to leave it for a "get great feedback on a PR" follow-up ๐Ÿ˜†

"tell reviewers how to test your code" can't be overstated.
i get WAY better feedback after adding a line or two communicating what type of feedback I'm looking for.

those other steps in doule, triple checking your work and ensuring that it's easy to review make for an inviting discussion.

thanks so much for the additions!

 

I prefer commit messages in past tense myself - for me when I look at a commit, I'm thinking "what did this commit do?" So it would make more sense to see the commit message in past tense.

 

yup. a lot of room for team preference on this one.
the linked article talks about the default preference being part of the linux heritage.