Pull Request Author ​

Open a good pull request ​

Title Structure ​

Standard ​

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

Should be summarize of git commit message

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.
• 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.
• 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 the current approach is 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.
• Add Reviewers : 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.
• Add 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.
• The size of the pull request
  • 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 review spends 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 the 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 Line of Code Count (LOC)

Regarding the pull request 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.

Open pull requests early on

• Do NOT wait to complete all requirements before opening a pull request:
  • On GitHub, open pull requests in draft mode since both version control providers have built-in support for this.
• Draft or Work-In-Progress (WIP) pull requests are encouraged to both get early feedback on implementation and share it with the team. Indeed, for efficiency purposes, the Team Lead can detect issues early in the implementation choices hence rerouting efforts earlier in the sprint. Besides, other team members can cherry-pick code from the branch even though it is not complete.

Best practices

• Share the implementation details with the team before implementing. The code reviewers and the author will get through code review process speedier and more efficient (decrease the code review time, and have fewer comments).
• Check open pull requests before implementing a new story. Prioritize open pull requests by fixing or replying to all the comments as soon as possible to improve the code review time.

Collaborate with code reviewers efficientlyNotify code reviewers

• A pre-requisite before notifying code reviewers, DO a self-code review before making the pull request ready for review. As mentioned above, it is encouraged to create a draft or WIP pull request, the author should do a self-code review to prevent code convention mistakes, typos, or to validate their overall solution again.
• Based on the Review Time section, an efficient review time is between 1 to 2 days on average, it is important to follow the pull request’s progress. Here are some best practices to notify code reviewers and improve the review time:
• GitHub will automatically notify the code reviewers about the pull request, the author of the pull request does NOT need to ask for code reviewing immediately after creating the pull request.
• If there are no activities on the pull request after a half-day, it is recommended to mention all code reviewers on the Slack dev channel to make sure all code reviewers already planned for code review.
• The author of the pull request can request the Team Lead to add priority labels for the pull request, all code reviewers can know when to review and follow by the order when having more than one pull request.
• In case there is a code reviewer who requested changes on the pull request, do not forget to re-request review after fixing or replying to the code reviewer’s comments.
• In terms of urgent features or issues, do not hesitate to send a message directly to the code reviewers.