Merge Requests

Merge Requests are time-consuming: they stop the motion for an engineer or a team, waiting for others to review and pipelines to succeed. We need to optimize these blocks to minimize their number and duration as much as possible to preserve our velocity.

Branch Naming

Branches must follow the convention: type/short-description (e.g. feat/selora-ai-onboarding, fix/frigate-stream-timeout). The branch name should map clearly to its GitLab Issue.

Creating a Merge Request

Every MR must be linked to its GitLab Issue or Epic. This is required for traceability across our OKR and Epic/Issue structure.

Every MR must include a description covering:

• Context and motivation: why this change is needed
• What was changed and how
• Testing instructions: how to verify the change works
• Screenshots or screen recordings for any UI/UX changes
• Link to the related GitLab Issue or Epic

Use Merge Request description templates whenever possible to ensure consistency and avoid forgetting required information.

MRs must be concise. Prefer one concern per MR. As a soft guideline, aim to stay under 400 lines of change. The more complex the MR, the more back and forth there will be, influencing other parts of the MR in turn. Complexity makes review time increase exponentially.

The MR must be assigned to the author(s), with reviewers assigned in the Reviewers field. Ping reviewers once the MR is ready. Use GitLab to manage the full lifecycle: request changes, resolve threads, approve.

Draft Merge Requests

If the MR is not ready to be merged, mark it as Draft using the three-dot menu in the upper right corner. Do not assign reviewers to a Draft MR, as it is unclear what is expected of them and approving a Draft does not make sense.

Before Requesting Review

1. Self-review your own diff first. Read it as if you were the reviewer, before anyone else does.
2. Run an AI review using Claude and/or Codex. Iterate until all critical issues are resolved.
3. Ask the AI to do a final check: clean code, no duplication, tests added or updated, security considered, documentation updated.
4. Only then assign reviewers and remove the Draft status.

Review Process

Once assigned as a reviewer, complete your review within one business day. The change is stale and blocking the author until you respond.

The purpose of a human review is to apply human judgement. Do not copy and paste an AI-generated review of the MR. We all have access to the same AI tools, there is no value in echoing one. It bloats the discussion, makes it harder for others to find real feedback, and AI reviews are typically posted as a single block rather than as inline comments on the precise lines where the feedback is useful. The author already ran an AI review before requesting yours (see above). Your job is to bring what the AI cannot.

When reviewing:

• Read the description and understand the context and motivation before looking at any code.
• Assess the change as a whole: does it make sense? Does it introduce unnecessary complexity?
• Review the data models. AI tends to take shortcuts here, and engineers are the quality gate for these decisions.
• Review the security implications of the change, not just the code itself.
• Check out the branch locally if the change touches UI or UX and navigate the feature yourself. User experience cannot be assessed from a diff alone.
• Comment inline on the specific lines that need attention, not in a single block.

After Approval

The author merges after receiving the required approvals. Commits are squash-merged automatically, enforced at the GitLab level.

If the author and reviewer disagree on a requested change and cannot resolve it through GitLab discussion, escalate to the CTO.