Clear, concise communication is essential in any software development project. A critical aspect of this is creating pull requests. A well-written pull request improves team collaboration and helps with monitoring and maintaining code quality. The whole pull request process can prevent poor or potentially unsafe code from making it into production. If you want to create quality pull requests, you need to follow some best practices when writing them.
Image Credit:Freepik
What is a pull request (PR)?
A pull request helps to explain the ‘what’ and the ‘why’ of your code. It’s an opportunity to make a strong case for why your code should make it into the main branch. Bad pull requests make it more difficult to collaborate and can slow down the development process. A bad PR is essentially one that is difficult to review and collaborate on. At the extreme, poor PRs can lead to a ‘tick the box’ style of reviewing in which approval happens without reviewing the code.
What is a PR in development? Developers use pull requests to explain their work to the rest of the team. Testers and other developers will review pull requests so they can identify and fix errors. What is PR in software development? Developers may also write PRs to request help if they have issues and can’t find a solution. They can then receive feedback and suggestions from other developers. For the process to run smoothly, developers must take time drafting the PR before sending it. Check here for more information about pull request best practices. Knowing best practices will help you to write quality PRs and write the next one with even more confidence and clarity.
Review your own code
Take the time to review your code before you create a PR. This enables you to catch common errors and makes the review process easier for testers or repo maintainers.
Create a draft pull request
Version control providers such as GitHub or GitLab allow you to create drafts of your pull requests. A draft PR allows you to collect input and suggestions from your team before you commit your changes. You can get helpful feedback by creating a draft PR for a code skeleton or even code that’s slightly buggy. Incorporating feedback early on will enhance the quality of your code and increase the chances of the PR being accepted on the first commit.
Keep pull requests short and focused
Your pull requests should be short and focused. If they are shorter, they are faster to review. There’s less room for introducing bugs and they provide a simple history of changes.
A pull request shouldn’t contain a whole lot of unrelated changes. It may consist of multiple commits but only if they are related to the task at hand. You can usually tell that your pull request is trying to do too much when you find it hard to write a concise description.
When writing pull requests, using PR templates can help you to keep them short and yet meaningful. They usually give you a guide to cover the problem, solution, impact, and testing plan.
Create clear titles and descriptions
The title and description are what reviewers will see first when looking at a pull request. You need to make sure they explain in clear terms what you changed and why. The goal is to be concise and not to write a whole novel.
Explain the ‘what’
It is important to explain your changes rather than just referencing a ticket. Try to be explicit and explain your changes in a few, short sentences.
Explain the ‘why’
Why you changed the code is often more important than what you changed. What business or engineering goal does the change achieve? This helps a reviewer to see the bigger picture. For example, the reason for making the changes could be to solve compliance issues.
Image Credit:Freepik
Include test results or other evidence
Before submitting your pull request, make sure you thoroughly test your changes. This will help to ensure that the changes don’t introduce regressions or new bugs. If possible, include your test results or other evidence of your testing in your pull request.
Some code, especially infrastructure code, is harder to test. If you can’t include your tests, you must let the reviewer know how you tested your changes. In some cases, you can explain to the reviewer how to test locally.
Add screenshots
Screenshots are particularly helpful for UI-related changes. A screenshot of ‘before’ and ‘after’ can really help the reviewer. GitHub supports adding images to a GitHub pull request description.
Avoid rewrites by getting feedback early
You can pay a price for going in the wrong direction for too long. You shouldn’t hesitate to ask for help if you really need it. If you do decide to ask for help, make it very clear what type of feedback you want. For example, if it is a work in progress you need to clarify that. Early feedback can enable early course correction. However, asking for urgent help when you haven’t really tried to find solutions can be annoying to others. You need to figure out when it’s important to write a pull request.
Final words
Hopefully, you now have a better idea of how to create a pull request. By following these tips, you can write clear, concise pull requests that are easy to review. This will help to ensure that your changes are accepted. Remember that PRs aren’t just for getting code approved but also help to foster collaboration and learning.
