Pull Request Authoring
The title (name) of the pull request must contain both the user story ID and the story title.
[<User Story ID>] <User Story Title>
The following title contains a user story ID and a story title from Shortcut:
[sc-32874] [UI] As a user, I can access my home screen
The following title contains a user story ID and a story title from Jira:
[ORANGE-1920] [Integrate] As a user, I can access my home screen
The following title contains a user story ID and a story title from GitHub:
[#123] [Backend] As a user, I can access my home screen
The description of the pull request must abide by this template.
The first line of a pull request description should be a link to the user story to make it easier for reviewers to get the complete requirement.
In terms of the body, there are three main sections for the author of the pull request to fill in:
Provide a description of what changes are being made. It should be informative enough that other developers do not have to read the pull request code or its whole description to understand what the pull request did.
This section should fill in the details, guidance, and additional information for reviewers to understand the changes.
For example, it can be used to inform about:
- A description of the issue that is being solved.
- Why is the current approach the best? Are there any links to the documents? Are there any shortcomings to the approach?
- How can the code reviewers test the pull request locally or remotely?
Proof of Work
Provide any visuals that can give assurance that the changes are safe to merge.
Here is an example of a good pull request:
In order to filter pull requests by user story types, and priorities, it’s recommended to:
- Assign the appropriate labels to the pull request. Labels are used to categorize the type of the pull request (
bug) and its priority (
- Assign a milestone to the pull request. Usually, a milestone corresponds to a release version.
At least two reviewers must be added to each pull request: either two team members in the same squad or, for a smaller project, one team member in the project and one “outsider” (not working in the project). The “outsider” must be defined as a reviewer member of the squad in the team organization diagram.
Among the reviewers must be the Team Lead and one other developer.
The scope of a pull request must be limited to a single story:
The pull request makes a minimal change that addresses just one story. Based on the areas of implementation, the author should create a pull request that implements only one area.
The pull request must also include tests for the changes made.
Extract some changes and refactorings into future stories if the requested changes are large and/or out of the initial scope of the pull request.
Advantages of one-story-scoped pull requests
A small pull request is reviewed faster, i.e., the code reviewer spends less time reviewing each pull request on average.
Code reviewers can easily just focus on one thing (one story) at the moment, i.e., a single list of acceptance criteria from one story helps the code reviewers spend less effort to check and validate.
Code reviewers and the author can easily and quickly detect bugs, i.e., code reviewers and the author can easily assess a small pull request. As a result, they can think more about edge cases, issues, or bugs.
The Team Lead can merge pull requests quickly: When working with a large pull request, normally, it will take a long time, and it will have lots of conflicts after rebasing compared to a small pull request.
An efficient pull request size is below 300 LOCs on average.
In case a one-story-related pull request might still involve many files and become overwhelming to review, it is recommended to split that into smaller ones. This enables earlier reviews and increases the focus for the reviewers.