Welcome, to what I hope will be something that I remember to do frequently which is a bullet point series.
This will be quick to read and hopefully useful little nuggets of knowledge that I may or may not be correct on haha.
Lets get to it...
This list is not exhaustive and might differ from your best practices but this is what I tend to try and go with and it seems to have improved our teams PR conversion
- Start with great branch names, I like to follow the convention of
grant/JIRA-1234/Add-Centralized-Cachingthis is useful as you can very quickly know who to go to for further information
- Make smaller pull requests, think about it how many of us would read in fine detail a 300 files changed PR
- Give yourself an early chance of finding any crap by self reviewing. You will not believe how much stuff I've found doing this. Add PR comments on anything you think might be confusing to someone else or the reasoning behind a decision. Draft PR's are your friend for this.
- Use descriptive and declarative commit messages the practice I use is to in my mind prefix all commit messages with "If applied this commit will..." This gives the reviewer a recipe for your PR and they can see how you got to the point you are at now.
- If you PR is for a bug fix where applicable add bug trap testing, this is a test around your bug fix. This allows the reviewer to see in terms of code what went wrong, what you did to fix it and also what you have done to test it, It also means that in future if your code is modified in any way the bug trap test may fail and prevent anyone introducing that same bug again.
- Use a PR template, knowing exactly where to go in a PR description every single time to get the information that you need will save you so much time long term trying to sift through a paragraph. I usually use something like this https://gist.github.com/GrantHair5/97b5564131376888cc45c4c35d68a3bc
- If it is a visual change please add a screenshot or GIF it helps the reviewer so much with understanding your change.
- Please spend the time to write a good PR description put yourself in others shoes. If you spend 5 minutes now that saves every reviewer 10 minutes and you have 3 reviewers there's a half hour saving right off the bat. "Fix broke stuff" doesn't cut it anymore haha
- Don't treat PR comments as a blocker, treat them as a way to collaboratively better your codebase, you might have missed something, PR's should be a safe space, if something is worth doing and someone else has put the effort into putting a change request in give it the credit it is due and talk it through with someone.
- Don't be scared to tell someone in a PR that they've done a great job, go crazy with emojis and GIFs it makes your repo a happier place and might give someone a little boost for the day. Be Kind to people.
- Red PR's are the best PR's, I call this decremental improvements and I'll write a little post about this later on but basically delete pointless stuff, we can always recover some comment that was in a code base. SCM LYF ❤️
I'll call time on this there, the bullet points got kinda lengthy but hopefully something in there will be of help to someone.
If you have any best practices you usually follow shoot them in the comments below I am always looking to improve processes.