Github Pull Request guidelines

You may be working in a small or large team or in a team that is distributed in multiple time-zones or as everyone is #WFH — pair programming is very difficult. Having a process will help you to streamline the Pull Request (PR) reviews by getting quicker feedback from collaborators and help you merge your PR.

To be able to ensure smoother and quicker PR review and merge, following process / responsibilities can be practiced:

As an Author of the PR:

If the developer is an artist then a pull request is the art.

While implementing the feature/task:

1. Make sure you have a good understanding of the Acceptance Criteria from the JIRA ticket or details of the Github issue.
2. Discuss with stakeholders like Tech Lead or an Architect about the proposed architecture of the feature/task integration (if required).
3. Make sure the architecture is following latest industry practices and is based on SOLID principles.
4. Write adequate test cases to validate the code against the Acceptance Criteria of the task/feature.

When you create the PR:

1. You should have a JIRA ticket with Acceptance Criteria or a Github issue that contains details of the task.
2. Provide code comments for areas that are harder to understand.
3. Provide a detailed description of the change you want to make.
4. Make sure the PR is small enough to be able to review quickly. There is no fixed size of a PR that you have to limit but I make sure the PR is not adding/modifying more than 30 files and the additions/deletions are not exceeding 1000 LOC.
5. In case the PR might become larger, divide the PR into smaller PRs and mention the order of the PR reviews in the PR description. For eg.: a PR for a typical feature implementation in a mobile app can be divided into:

• PR #1: Implement UI of the feature with accessibility support and adequate test cases
• PR #2: Implement API/DB integration with adequate test cases
• PR #3: Implement feature configurations like feature toggles, analytics and localisation
• Imp note: Do not divide a PR by having feature implementation in one PR and the test cases in another PR. The test cases must always go hand in hand with the actual implementation.

After the PR is created:

1. Review your own PR. You may find potential issues and fix them quickly.
2. Take feedback on the PR positively, be patient and a good listener. Be open to learning from your colleagues.
3. If the reviewer has requested changes on the PR and you are not fully clear about the changes, try to connect directly with the reviewer over other communication channels such as Zoom, Slack or MS Teams. Communication away from Github is often the easiest way to get understanding about the comments.
4. In case establishing direct contact with the reviewer is not possible (for eg. reviewer is in different timezone), politely reply on the PR comment asking for more information and ask for any suggestion on how the solution should look like.

As a Reviewer of the PR:

Be respectful when providing feedback on the PRs. The goal is to find the issues beforehand and improve the code base.

1. Read through the PR description, JIRA ticket / Github issue to understand the change the author wants to introduce.
2. It is a good practice to checkout the branch and run the solution. This is important because of cases like you can’t see folder structure, unused imports (if lint is lenient), issues with the UI/UX, etc.
3. The PR should be reviewed entirely in one go. The time-to-merge the PR can be reduced significantly if the author gets all feedback in one go. Code reviews in instalments creates delays and frustration in the team.
4. Do not request changes for simple questions; this is true for most cases. However, there can be exceptions like if you feel the PR should not be merged unless the question is answered.
5. Be clear and reasonable when reviewing PRs. Provide examples in comments so that the author understands the changes you are requesting. For eg. instead of saying “Improve this block of code.”, suggest exactly what changes are expected with any (pseudo) code.
6. Be prompt and watch the PRs on which you have requested changes. This will ensure you don’t miss out re-reviewing PR when the comments are addressed.
7. Set a dedicated time every day to review PRs. Reviewing PRs is very much part of our day to day task.
8. Even if the PR is reviewed and approved by other collaborators/maintainers, review the PR properly. You may notice some areas of improvement or bugs that other reviewers didn’t notice.

As the Team:

Code reviews are as important as writing the actual code. Therefore you should aim to include time for code reviews in your daily task lists.

1. Add Code Review in your JIRA workflow
2. Code reviews is a way to collaborate with multiple developers from different backgrounds/timezones. The collaboration needs to be non-judgemental with a common goal of learning and sharing.
3. Receive any feedback gratefully as an opportunity to learn and to share knowledge.