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 🙌
Oldest comments (4)
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.
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!