Pull Request Authoring

Structure

Title

The title (name) of the pull request must contain both the user story ID and the story title.

[<User Story ID>] <User Story Title>

For example:

• 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
  

When the pull request references a GitHub issue, the user story ID must be prefixed with #. This shorthand will generate a convenient link to the GitHub issue in the release notes.

Description

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.

For example:

https://app.shortcut.com/nimble-website/story/23792

In terms of the body, there are three main sections for the author of the pull request to fill in:

• What happened

  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.

  It is not recommended to copy the description of the user story to the pull request description because the first line of the pull request attaches the link of the user story.

  GitHub allows pull requests to be automatically linked with issues with a specific keyword in the description. For example, this statement Closes #980 will automatically link issue 980 with the current pull request.

• Insight

  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?

  A well-written pull request can go a long way to make code reviews speedier and overall more efficient 💪

• 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:

Metadata

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 (feature, chore, or bug) and its priority (high, normal, or low).
• Assign a milestone to the pull request. Usually, a milestone corresponds to a release version.

Reviewers Assignment

• 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.

Single-story Scope

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.

Optimal Size

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.