Pull Requests
Pull requests (often abbreviated to PR) are a key part of the development lifecycle. They allow for changes to be reviewed by peers before being merged into the main codebase. This process helps to ensure that all code meeting the quality standards set by the team, provides opportunities for knowledge sharing, reduces the likelihood of bugs being introduced and, more generally, improves team cohesion.
In their simplest form, a pull request signals the intent to merge one branch into another. However, instead of directly merging it provides a platform for discussion and review before the merge actually occurs. The specifics to how pull requests are made, and the functionality around them, depends on the specific platform being used as the remote repository for source control.
Pull requests can also be used to gather feedback about an in-progress change, without any intent of merging the branch in its current state.
Creating a pull request
This guide will not cover the specifics of how to raise a pull request on any particular platform; instead it will focus on the steps which can be taken to ensure a high quality pull request.
A pull request usually consists of two parts:
- Subject line: A brief description of the changes being made
- Description: A more detailed explanation of the changes, including any context which may be required to understand the changes
When working with a ticketing system, including the ticket number in the subject line can be useful to link the pull request to the ticket. For example:
PROD-1234: Account total lifetime value calculation
This allows a reviewer to quickly compare the changes made in the pull request to the requirements outlined in the ticket, while also providing a small insight into the change, without having to open the pull request. Ideally this subject line should be kept as concise as possible.
The description is where the majority of the details should be included. This should provide a detailed explanation of the changes made, the reasons for the changes, and any potential impacts of the changes. This should be written in a way that someone who is not familiar with the codebase can understand the changes being made. For example:
Added apex class to calculate the total lifetime value of an account using the sum of all opportunities associated with the account. This only affects accounts when an opportunity is created or updated.
Reviewing a pull request
When reviewing a pull request, it is important to consider the following:
- Functionality: Does the code do what is expected? Does it meet the requirements outlined in the ticket?
- Quality: Is the code well written? Is it easy to understand? Are there any potential issues with the code?
- Security: Are there any potential security vulnerabilities in the code? Are permissions being enforced?
- Performance: Are there any potential performance issues with the code? Are there any unnecessary queries or loops?
- Testing: Are there tests included with the code? Do the tests cover all possible scenarios? Are the tests passing?
- Style: Does the code follow the team's style guide? Is the code consistent with the rest of the codebase?
Overall, peer review is a subjective process, but it is important to note that the code is being reviewed and not the developer who wrote the code. The goal of a peer review is to improve the quality of the codebase and to keep it consistent, not to criticise the developer.
Not all feedback needs to be negative - if you see something you like, let the developer know!
Automation
Pull requests can also offer a platform for automated processes to be engaged, usually called pipelines. These pipelines can be used to run pieces of code which can check for common issues, such as syntax errors, or more complex issues such as security vulnerabilities. These pipelines can be configured to run automatically when a pull request is raised, providing immediate feedback to the developer on the quality of their code.