Towards Better Pull Requests
I’m going to share with you some tips on what a good pull request looks like. If you’re unfamiliar with pull requests, they are a way of requesting changes to be merged into a project’s main branch, usually on an online platform like GitHub.
Pull requests are an awesome mechanism to enable collaboration with others, get feedback on your work, and keep track of the project’s history.
Remember that whilst I’m talking about code in this article, just about anything based on text can be used with a git repository. Code, your CV, your school curriculum, your novel, your manifesto.
Not all pull requests are created equal. Some are clear, concise, and easy to review, while others are messy, confusing, and hard to understand. How can you make sure your pull requests fall into the former category? Here are some dos and don’ts of pull request etiquette:
- Do: Keep it small, and address the minimum changes needed to achieve the aim. Try creating other issues to update out of scope items you find as you wade through the code.
- Dont: change things that are not in the scope of the change you are trying to make.
- Do: Set context. Write a descriptive title and summary for your pull request. Explain what you did, why you did it, and how it affects the project. Use bullet points or lists to highlight the main changes. Include screenshots or gifs if they help illustrate your work. If you are using a different project management tool such as trello, Jira, Azure devops board, a link to the issue / ticket you are trying to fix should cover this.
- Don’t: Write vague or generic titles like “Update README.md” or “Fix bug”. These don’t tell the reviewer anything about your pull request and make it harder to find in the project’s history. Also, avoid writing long paragraphs of text that nobody will read.
- Do: Follow the project’s coding style and conventions. Use consistent indentation, spacing, naming, and formatting. If the project has a style guide or a linter, follow it. If not, try to match the existing code as much as possible.
- Don’t: Introduce unnecessary changes that are not related to your pull request. For example, don’t reformat the whole file, change variable names, or add comments that are not relevant. These make your pull request harder to review and may cause unnecessary conflicts with other branches.
- Do: Break down your pull request into small and logical commits. Each commit should have a clear purpose and message. Use verbs like “Add”, “Fix”, “Refactor”, or “Remove” to describe what you did in each commit. your commits should tell the story of how you did what you did. This makes your pull request easier to review and revert if needed.
- Don’t: Squash all your changes into one big commit or make multiple commits with the same message. This makes your pull request harder to review and understand.
- Do: Test your code before submitting your pull request. Run the projects test pack, and fix any errors or warnings generated. Make sure it works as expected and doesn’t break anything else in the project.
- Don’t: Submit your pull request without testing your code or with known bugs or errors. This shows a lack of care and professionalism and wastes the reviewer’s time.
- Do: Break the rules when it makes sense, in order to aid the reader.
- Do: Review your own code review first. Drink some coffee first though. Often it's eye-opening to see how your pull request looks to a reviewer. Help them out with a couple of explanations.
I hope this helps you improve your pull request communication skills and make your collaboration more enjoyable and productive.
Merry engineering!
