Version 1.0

Status Active

Owner Head of Engineering

Last Updated 2026-06-06

SOP: Pull Requests and Code Review

1. Purpose

The purpose of this SOP is to make code changes reviewable, traceable, and safe to merge.

This SOP defines how Pull Requests are created, reviewed, updated, approved, and merged. It also defines the responsibilities of PR authors, reviewers, specialized reviewers, and authorized approvers.

The goal is to ensure that every code change is:

linked to a valid ticket,
small enough to review properly,
clearly described,
reviewed by the appropriate people,
validated by required checks,
and traceable after merge.

2. Scope

This SOP applies to all code, configuration, infrastructure, CI/CD, documentation, and repository changes submitted through GitHub Pull Requests.

It applies to:

Frontend frontend application changes,
Backend backend application changes,
DevOps infrastructure, deployment, and CI/CD changes,
QA test automation, QA tooling, and test-related changes,
Engineering shared engineering standards, scripts, and repository configuration.

This SOP does not replace the Ticket Management SOP, Git Flow SOP, QA SOP, or Deployment SOP. It connects to those procedures where appropriate.

3. Core Rule

Mandatory Every code change must go through a Pull Request before it is merged.

A Pull Request must be linked to a valid ticket according to the Ticket Management SOP.

A Pull Request must not be merged until:

the PR is linked to the related ticket,
the GitHub PR template and checklist are completed properly,
required reviewers have approved the change,
required checks are passing,
review comments are addressed,
and the PR is ready to be merged into the target branch.

4. Rule Strictness

Level	Meaning
Mandatory	Must be followed unless there is an approved and documented exception.
Default	Should normally be followed, but exceptions are allowed when justified.
Recommended	Encouraged, but not strictly required in every case.

5. Definitions

Term	Meaning
Pull Request / PR	A GitHub request to merge changes from one branch into another branch.
PR Author	The person who creates the PR and owns it until it is merged or closed.
Reviewer	A person or team responsible for reviewing the PR before merge.
Specialized Reviewer	A person or team required to review specific types of changes, such as DevOps, security, infrastructure, CI/CD, or repository configuration changes.
Required Checks	GitHub checks, CI jobs, build jobs, tests, linters, or ruleset checks that must pass before merge.
Draft PR	A PR opened for visibility or early feedback, but not yet ready for formal review.
Ready for Review	The PR state where the author considers the change ready for formal review.
Merge Commit	The default merge method where the PR branch is merged into the target branch using a merge commit.

6. Roles and Responsibilities

Role	Responsibilities
PR Author	Creates the PR, links the ticket, completes the PR template and checklist, keeps the PR updated, requests review, responds to comments, ensures checks are passing, and merges the PR when ready.
Reviewer	Reviews the PR for correctness, maintainability, readability, risk, standards, and test coverage. Provides clear feedback and approves only when satisfied.
Specialized Reviewer	Reviews specific areas of responsibility when required by repository rules, CODEOWNERS, GitHub rulesets, or reviewer judgment.
QA	Verifies the related ticket after the PR is merged and available in the correct test environment, when QA verification is required.
DevOps	Reviews infrastructure, CI/CD, deployment, environment, repository configuration, and operationally sensitive changes when required.
Head of Engineering	Owns the process, resolves escalations, approves exceptions when needed, and ensures the workflow is followed.
Authorized Approver	A person with the appropriate repository role who may merge, override, or bypass repository rules only when justified and documented.

7. Pull Request Rules

7.1 Every PR must be linked to a ticket

Mandatory Every PR must reference the related ticket.

The ticket link must be included in the PR description, using the GitHub PR template or another clearly visible location.

If a PR is not linked to a ticket, it should not be reviewed or merged until the ticket link is added.

7.2 Every PR must complete the GitHub template and checklist

Mandatory The PR author is responsible for completing the GitHub PR template and checklist accurately before requesting review.

The exact template may change over time. The author is responsible for following the current template that exists in the repository.

Checklist items must not be checked unless they are actually complete. If a checklist item does not apply, the author must mark it as not applicable or explain why it does not apply.

7.3 PRs should represent one ticket or one logical unit of work

Default A PR should normally represent one ticket or one logical unit of work.

A PR may include more than one ticket only when the tickets are tightly related and the combined change remains easy to review.

Mandatory A PR must not mix unrelated changes.

Good examples:

Add password reset endpoint.
Fix mobile layout on the login page.
Add staging deployment workflow.
Update tests for the password reset flow.

Bad examples:

Password reset, dashboard refactor, dependency upgrades, and unrelated UI fixes in the same PR.
Bug fix mixed with large formatting changes.
Feature implementation mixed with unrelated cleanup.

7.4 Large PRs may be rejected for splitting

Mandatory A reviewer may request that a PR is split if it is too large or too mixed to review properly.

A PR is considered too large when the reviewer cannot reasonably understand the purpose, assess the risk, and provide meaningful feedback in a reasonable amount of time.

Splitting a PR is not a punishment. It is a quality and reviewability requirement.

7.5 PRs target development by default

Mandatory Pull Requests must target the development branch by default.

Changes should flow into master or main only through the agreed release process. Hotfixes should also target development unless the Head of Engineering or authorized responsible person explicitly approves a different path.

7.6 Merge commits are the default merge method

Default The default merge method is merge commit unless the repository owner or Git Flow SOP defines otherwise.

Merge strategy may be revisited in the Git Flow SOP.

8. Draft Pull Requests

Recommended Draft PRs may be opened early for visibility, collaboration, or early feedback.

Draft PRs are useful when:

the author wants early technical feedback,
the work is large and should be visible before completion,
the author wants to validate CI behavior before formal review,
or the change needs early alignment with another team.

A Draft PR is not considered ready for formal review.

Formal review starts only when:

the PR author marks the PR as ready for review,
the PR template and checklist are complete,
the related ticket is linked,
the PR is no longer expected to change significantly,
and the correct reviewer or reviewer team has been requested.

9. Reviewer Assignment

9.1 Default reviewer assignment

Mandatory The PR author is responsible for ensuring that the correct reviewer or reviewer team is requested when the PR is ready for review.

By default, review should be requested from the configured reviewers team.

One approval from the reviewers team is required for normal PRs unless repository rules require more.

9.2 Specialized reviewer assignment

Mandatory Some changes may require additional specialized review.

Repository rules, CODEOWNERS, GitHub rulesets, or path-based rules may automatically assign additional reviewers when specific files or areas are changed.

Examples of changes that may require specialized review:

DevOps CI/CD configuration changes,
DevOps infrastructure or deployment changes,
Engineering repository configuration changes,
Engineering security-sensitive changes,
Backend database migrations or data model changes,
Backend authentication or authorization changes,
QA test automation or QA tooling changes.

If specialized reviewers are automatically requested, their review requirement must be respected. The PR author must not remove required reviewers unless there is a documented and approved reason.

9.3 Additional reviewer requests

Default Reviewers may request additional approval from another individual, team, technical owner, DevOps, QA, or the Head of Engineering when the change is high-risk or outside their area of confidence.

Additional review may be requested for:

authentication or authorization changes,
payment, billing, financial, or reward logic,
database migrations,
infrastructure or CI/CD changes,
security-sensitive changes,
large refactors,
production hotfixes,
changes with significant user impact,
or changes that cross team boundaries.

10. Review Expectations

10.1 Reviewer responsibilities

Reviewers should review for:

correctness,
maintainability,
readability,
security,
performance,
test coverage,
edge cases,
consistency with existing patterns,
and risk to users, systems, or deployments.

Reviewers should provide clear, actionable feedback.

If a reviewer is not comfortable approving the PR, they should request clarification, request changes, or involve another reviewer.

10.2 Author responsibilities

Mandatory The PR author owns the PR until it is merged or closed.

The PR author is responsible for:

keeping the PR up to date,
responding to review comments,
making requested changes,
explaining when a requested change is not appropriate,
keeping the related ticket updated,
ensuring required checks pass,
requesting additional review when needed,
and merging the PR when it is ready.

10.3 Review comments

Mandatory Review comments must be addressed before merge.

The PR author is responsible for resolving review comments.

A review comment is considered addressed when:

the requested code change is made,
the author provides an explanation and the reviewer accepts it,
the comment is no longer relevant after other changes,
or the topic is escalated and a decision is made.

Review comments should not be ignored, silently resolved, or dismissed without explanation.

10.4 Disagreements

Default If the PR author and reviewer disagree, they should resolve the discussion in the PR comments whenever possible.

If agreement cannot be reached, the discussion should be escalated to the responsible technical owner, team lead, or Head of Engineering.

The final decision should be documented in the PR comments.

11. Checks and Pipelines

Mandatory Required checks must pass before a PR is merged.

Required checks may include:

build checks,
unit tests,
integration tests,
linting,
type checks,
security checks,
ruleset checks,
or deployment preview checks.

A PR with failing required checks must not be merged.

If a check fails, the PR author is responsible for investigating and resolving the failure.

A failing check may be bypassed only when:

the failure is unrelated to the PR,
the reason is documented in the PR,
an authorized person approves the bypass,
and any required follow-up action is documented.

12. Review and Merge Timing

12.1 First review feedback

Default A PR should receive first review feedback within one business day after it is marked ready for review.

First feedback may be:

approval,
requested changes,
questions or clarification,
or a comment explaining when review can happen.

12.2 Merge or documented blocking reason

Default A PR should be merged or have a documented blocking reason within two business days after it is marked ready for review.

If the PR is not merged within two business days, the PR must include a comment explaining why.

Valid blocking reasons include:

more work is needed,
reviewer availability,
author availability,
sickness or time off,
failing checks,
open review comments,
unclear requirements,
waiting for another team,
waiting for QA,
or a deliberate decision to postpone merge.

PRs should not remain open without clear ownership or explanation.

13. Merge Rules

13.1 Default merge owner

Default The PR author merges the PR after approval and passing checks.

The author remains responsible for the PR until it is merged or closed.

13.2 Merge requirements

Mandatory A PR may be merged only when:

the PR is linked to a valid ticket,
the PR template and checklist are complete,
the PR targets the correct branch,
at least one required approval exists,
additional required reviewers have approved when applicable,
required checks are passing or an approved bypass is documented,
review comments are addressed,
there are no unresolved blocking discussions,
and the PR is ready to be merged.

13.3 Authorized merge or bypass

Mandatory Repository merge rules may only be bypassed by an authorized person with a documented reason.

Bypass may be allowed for:

urgent production incidents,
broken checks unrelated to the PR,
repository configuration problems,
time-sensitive operational fixes,
or other explicitly approved exceptions.

When a merge rule is bypassed, the PR must include a comment with:

bypass reason,
approved by,
risk or impact,
and follow-up action, if needed.

14. Ticket Updates and QA Handoff

Mandatory The related ticket must be updated according to the Ticket Management SOP.

When a PR is opened for review, the related ticket should be moved to In Review.

When a PR is merged and the change is available in the correct test environment, the related User Story or Issue should be moved to Ready for Test when QA verification is required.

If a PR is closed without merge, the related ticket must be updated with the reason and moved to the appropriate status.

15. Procedure

15.1 Creating a PR

Confirm that a valid ticket exists.
Create a branch according to the Git Flow SOP.
Implement the change.
Open a PR targeting development.
Use a clear PR title.
Complete the GitHub PR template and checklist.
Link the related ticket.
Confirm the PR contains one ticket or one logical unit of work.
Confirm unrelated changes are not included.
Open as Draft if the PR is not ready for formal review.

15.2 Requesting review

Confirm the PR is ready for formal review.
Confirm the template and checklist are complete.
Confirm required checks are passing or failures are explained.
Mark the PR as ready for review if it was opened as Draft.
Request review from the configured reviewers team.
Ensure specialized reviewers are requested when required by repository rules or by the type of change.
Move the related ticket to In Review.

15.3 Reviewing a PR

Review the PR description and linked ticket.
Review the scope of the PR.
Check whether the PR contains unrelated changes.
Review the code for correctness, maintainability, readability, security, and risk.
Check whether tests or validation are appropriate.
Request changes, ask questions, approve, or request additional review.

15.4 Updating a PR after review

Respond to review comments.
Make required changes.
Explain any requested change that will not be implemented.
Push updates to the PR branch.
Confirm checks pass again.
Request re-review when ready.

15.5 Merging a PR

Confirm the PR is linked to a valid ticket.
Confirm required approvals exist.
Confirm specialized reviewers have approved when required.
Confirm required checks pass.
Confirm review comments are addressed.
Confirm the PR targets the correct branch.
Merge using the default merge method.
Update the related ticket according to the Ticket Management SOP.

16. Exceptions

16.1 Urgent production incidents

For urgent production incidents, the review process may be accelerated.

However, the following are still required:

a ticket must exist or be created as soon as possible,
a PR must be created,
the PR must explain the incident or urgent fix,
required checks must pass unless an authorized bypass is documented,
and follow-up cleanup must be documented if normal process steps were skipped.

the related ticket is linked,
the PR template and checklist are complete,
the PR contains one ticket or one logical unit of work,
unrelated changes are removed,
required reviewers have approved,
specialized reviewers have approved when required,
required checks are passing or an approved bypass is documented,
review comments are addressed,
the PR is merged into the correct target branch,
and the related ticket is updated.

18. Short Checklist

18.1 Before opening a PR

Ticket exists.
Branch was created according to the Git Flow SOP.
Change is related to one ticket or one logical unit of work.
Unrelated changes are not included.
Code builds locally when applicable.
Tests were added or updated when applicable.

18.2 Before requesting review

PR targets development.
PR title is clear.
PR template is completed.
PR checklist is completed accurately.
Related ticket is linked.
Required checks pass or failures are explained.
Correct reviewer or reviewer team is requested.
Specialized reviewers are requested when required.
Related ticket is moved to In Review.

18.3 Before approving a PR

Scope is clear and reviewable.
PR does not mix unrelated changes.
Linked ticket matches the PR scope.
Implementation is understandable and maintainable.
Risks are acceptable or documented.
Tests or validation are appropriate.
Required checks are passing or failures are explained.

18.4 Before merging a PR

Required approval exists.
Additional required approvals exist when applicable.
Required checks pass.
Review comments are addressed.
No unresolved blocking discussions remain.
PR uses the correct target branch.
Related ticket is updated after merge.

19. Workflow Diagram

19.1 Pull Request lifecycle

flowchart TD
  A[Ticket Exists] --> B[Author Creates Branch]
  B --> C[Author Implements Change]
  C --> D{Ready for Formal Review?}
  D -- No --> E[Open Draft PR]
  E --> C
  D -- Yes --> F[Open or Mark PR Ready]
  F --> G[Complete PR Template and Checklist]
  G --> H[Request Reviewers Team]
  H --> I{Specialized Review Required?}
  I -- Yes --> J[Request Specialized Reviewer]
  I -- No --> K[Review Starts]
  J --> K
  K --> L{Review Approved?}
  L -- No --> M[Author Addresses Comments]
  M --> K
  L -- Yes --> N{Required Checks Passing?}
  N -- No --> O[Author Fixes Checks]
  O --> K
  N -- Yes --> P[Author Merges PR]
  P --> Q[Update Related Ticket]
  Q --> R{QA Required?}
  R -- Yes --> S[Move Ticket to Ready for Test]
  R -- No --> T[Move Ticket to Appropriate Status]
  S --> U[PR Complete]
  T --> U[PR Complete]

19.2 Review escalation flow

flowchart TD
  A[Reviewer Reviews PR] --> B{Comfortable Approving?}
  B -- Yes --> C[Approve PR]
  B -- No --> D{Issue Type}
  D -- Code Concern --> E[Request Changes]
  D -- Unclear Scope --> F[Ask Author for Clarification]
  D -- High Risk --> G[Request Additional Reviewer]
  D -- Specialized Area --> H[Request Responsible Team]
  E --> I[Author Updates PR]
  F --> I
  G --> J[Additional Review]
  H --> J
  I --> A
  J --> K{Resolved?}
  K -- Yes --> C
  K -- No --> L[Escalate to Technical Owner or Head of Engineering]

20. Version History

Version	Date	Author	Changes
0.1	2026-06-06	Head of Engineering	Initial draft.
1.0	2026-06-09	Head of Engineering	Active.