Review Workflow

Purpose: Guide contributors through creating and reviewing merge requests to maintain code quality and foster collaborative development

Audience: Developers and contributors participating in code writing and reviewing

Status: Draft

Rationale

This workflow establishes a consistent process for code review that ensures:

  • Code quality is maintained through peer review
  • Knowledge is shared among team members
  • Changes are properly documented and communicated
  • Multiple perspectives are considered before merging
  • Authors receive timely feedback to maintain productive workflow

Quick Reference

For Authors:

  • Mark as draft until ready for review
  • Request 2-5 reviewers (buddy, success partner, not product manager)
  • Respond to feedback within a day
  • Need 2+ approvals before requesting product manager review

For Reviewers:

  • Review within one week of assignment
  • Use template with review checklist
  • Provide constructive feedback

Workflow Steps

1. Prepare Draft Merge Request

Who: Merge Request Author

When: While work is in progress and not ready for review

Actions:

  • Mark MR as draft (e.g., "Draft: Meeting notes")
  • Continue developing until ready for review

Result: MR exists but reviewers know not to review yet

2. Make Merge Request Ready for Review

Who: Merge Request Author

When: Code is complete and ready for peer review

Actions:

  • Follow the Merge Request template
  • Write review guidelines specific to this MR
  • Perform a thorough self-review of the MR
  • Remove draft status

Result: MR is clearly documented and ready for reviewers

3. Request and Manage Reviews

Who: Merge Request Author

When: After MR is ready for review

Actions:

  • Request 2-5 reviewers (e.g., buddy and success partner, but not the product manager)
  • Once you receive a review, immediately improve MR according to the feedback
  • Resolve all open threads
  • If no feedback within a week, ping the reviewers
  • Assign additional reviewers if needed for faster/more feedback

Result: MR receives timely reviews and continuous improvements

4. Handle Review Feedback

Who: Merge Request Author

When: After receiving change requests from reviewers

Actions:

  • If you agree with requested changes, apply them
  • If you disagree with requested changes, escalate to product manager
  • If changes would be substantial, create a follow-up issue or re-request review from the original reviewer

Result: Review feedback is addressed and reviewer concerns are resolved

5. Finalize for Merge

Who: Merge Request Author

When: After receiving 2+ approvals

Actions:

  • Add the label "MR:please merge"
  • Request review from product manager

Result: MR is approved and queued for final merge

6. Conduct Review

Who: Assigned Reviewer

When: Within one week of being assigned

Actions:

  • Check if the MR uses the proper template and includes a review guide; if either is missing, request them
  • Copy the review template with checkboxes about what you reviewed
  • Review the MR completely before submitting feedback
    • If you cannot finish within a day, submit partial reviews
  • Provide constructive feedback
  • Request changes if necessary, or approve if satisfied
  • Comment on parts that could be improved or need clarification

Result: Author receives actionable feedback to improve the MR

Special Cases

Disagreement on Requested Changes

If the author disagrees with requested changes:

  1. Author escalates to product manager
  2. Product manager makes final decision
  3. Author implements decision or creates follow-up issue

Substantial Changes Required

When reviewer feedback would require substantial work:

  1. Author creates a follow-up issue for the substantial changes
  2. Current MR can proceed without those changes, OR
  3. Author re-requests review from original reviewer after substantial changes

No Reviews Received

If author hasn't received feedback within a week:

  1. Author pings assigned reviewers
  2. Author can assign additional reviewers
  3. Author can escalate to product manager if needed

Examples

Example 1: Standard MR Flow

Day 1: Author completes feature, follows template, requests 3 reviewers
Day 2: Reviewer 1 provides feedback requesting minor changes
Day 2: Author makes changes, resolves threads
Day 3: Reviewer 2 approves
Day 4: Reviewer 3 approves
Day 4: Author adds "MR:please merge" label, requests PM review
Day 5: PM approves and merges

Example 2: MR with Disagreement

Day 1: Author requests review
Day 2: Reviewer requests architectural change
Day 2: Author disagrees, escalates to PM
Day 3: PM decides to proceed with current approach
Day 3: Author documents decision in MR
Day 4: Reviewer approves based on PM decision
Day 5: Second approval received, PM merges
  • .gitlab/merge_request_templates/ - MR templates to follow
  • Review guidelines (should be filled out in each MR by author)

Troubleshooting

Common Issues

Problem: No reviews received within a week Solution:

  1. Ping assigned reviewers in MR comments
  2. Assign additional reviewers
  3. Escalate to product manager if still no response

Problem: Review template or review guide missing from MR Solution: Reviewer should immediately request these in the MR before conducting review

Problem: Reviewers keep finding new issues on each review round Solution:

  1. Ensure reviewers complete full review before submitting
  2. Use the review checklist template
  3. Consider scheduling a synchronous review session for complex MRs

Problem: Author and reviewer stuck in disagreement Solution: Escalate to product manager for decision

Open Points

Notes

  • Fast reviews (within 1-2 days) are very helpful to maintain productive workflow
  • Partial reviews are acceptable if full review cannot be completed within a day
  • All feedback should be constructive and focused on improving the code