SYNCRO uses a .github/CODEOWNERS file to enforce required reviews based on code ownership boundaries. This document outlines the review process, escalation paths, and handoff procedures.
Related Documentation:
- Directory Ownership Matrix - Detailed ownership information
- Ownership Quick Reference - Quick lookup guide
- CODEOWNERS - GitHub enforcement
| Area | Owner | Primary Responsibility |
|---|---|---|
| client/ | Frontend Team | UI/UX, components, hooks, styles, E2E tests |
| backend/ | Backend Team | APIs, services, business logic, database queries |
| contracts/ | Smart Contract Team | Blockchain logic, delegation, renewal windows |
| supabase/ | Infrastructure Team | Database migrations, RLS policies, seed data |
| sdk/ | SDK Team | Reminder SDK, logger, public APIs |
| shared/ | Platform Team | Shared types, domain models |
| docs/ | Documentation Team | Technical documentation, guides |
| scripts/ | DevOps Team | Automation scripts, utilities |
| .github/ | DevOps/Maintainer | CI/CD workflows, branch protection, automation |
For detailed ownership information, see Directory Ownership Matrix.
- Minimum reviewers: 1 required approval from the code owner
- Auto-request: GitHub automatically requests reviews when PRs touch owned files
- Merge criteria: PR must have approved reviews before merging to
main
When a PR touches files in multiple ownership areas:
- GitHub automatically requests reviews from all affected owners
- Each owner must approve changes in their area
- No merge until all approvals received (enforced by branch protection)
-
Before opening a PR:
- Check
.github/CODEOWNERSto identify required reviewers - Leave a comment tagging owners if your change spans multiple areas
- Link related issues in the PR description
- Check
-
While in review:
- Address feedback promptly
- If review stalls, escalate to the next level (see below)
- Request re-review after making changes
-
Addressing feedback:
- Discuss disagreements in PR comments (never commit controversial changes without consensus)
- If ownership is unclear, involve the maintainer (@Calebux)
-
Reviewing code in your area:
- Focus on design, logic, security, and maintainability
- Check for test coverage and documentation
- Ensure changes align with codebase conventions
-
Cross-area changes:
- If a change affects your area but originated in another, review carefully but defer to the primary owner
- Comment to flag concerns but allow the primary owner to make final decisions
-
Approval criteria:
- Code is tested (unit tests pass, E2E tests pass if applicable)
- Documentation is updated
- No security or performance regressions
- Follows project conventions
- PR automatically assigned to code owner
- If no response in 24 hours, leave a comment mentioning the reviewer
- If no response in 48 hours, escalate to Level 2
- Tag the next senior team member in the same area
- Leave comment with
@mentionand brief summary of the change - Provide context: "This PR has been pending review for 48h on [feature/area]"
- Tag @Calebux for urgent reviews
- Use clear subject line:
[URGENT] PR #123 - [area] - awaiting review - Include:
- Why this is urgent
- Which owner hasn't responded
- How long it's been pending
- Impact of delay
If a review is genuinely blocked (e.g., reviewer unavailable):
- Owner can request: PR reviewer to unblock → reply with timeline
- Team can request: Maintainer to bypass or reassign review
- Maintainer action: Can approve on behalf of owner with documented reason in PR
- Must be approved by @Calebux
- Include rationale for ownership changes
- Update this document if boundaries change
- Fast-track available for urgent production issues
- Must include proof of criticality (incident report, customer impact)
- Requires 1 owner approval + 1 maintainer approval minimum
- Follow normal merge once expedited
- Still require review from affected area owners
- Can be approved by a single senior contributor
- No strict timeline if no code changes
- PRs > 400 lines require advance planning
- Create tracking issue or RFC (Request for Comment)
- Get owner sign-off before opening PR
- May be split into multiple PRs by owner request
The main branch is protected with:
- ✅ Require pull request before merging
- ✅ Require CODEOWNERS review approvals
- ✅ Require status checks to pass (tests, type checks, linting)
- ✅ Require up-to-date branches before merging
- ✅ Dismiss stale review approvals when new commits pushed
- ✅ Restrict who can push to matching branches (maintainers only)
To propose ownership changes:
-
Open an issue with:
- Proposed change
- Rationale (why existing structure is inadequate)
- Impact (which teams affected)
-
Create a PR that:
- Updates
.github/CODEOWNERS - Updates this document with new boundaries
- Tags @Calebux for discussion
- Updates
-
Approval: Requires sign-off from affected owners + maintainer
Q: Can I bypass CODEOWNERS review?
A: No. Only @Calebux can do this via branch protection settings, and only for emergencies.
Q: What if I own code in multiple areas?
A: You must review your changes in each area independently. Consider splitting the PR by area.
Q: How long should review take?
A: Target: 24 hours for initial review, 48 hours for approval. Escalate after 48h.
Q: What if the owner is on vacation?
A: Set status in GitHub/Slack. Assign a backup owner or escalate to maintainer.
Q: Can I merge my own PR?
A: No. Even maintainers require at least 1 peer review. Merge only after approval.
- Directory Ownership Matrix - Detailed ownership for all directories
- Ownership Quick Reference - Quick lookup guide
- CODEOWNERS - GitHub enforcement file
- Contributing Guide - Contribution guidelines
Last updated: 2026-05-27
Maintained by: @Calebux