Collaboration
Code review - the comment is on a line that moved
What it takes to keep a conversation attached to code that is rewritten underneath it while the conversation is still going.
What this board gets wrong on purpose
The tension
Comments are re-anchored by mapping the old head to the new one through an interdiff, with a context hash as the fallback and an "outdated" marker when both fail - and roughly 9% of comments go outdated on a typical force-push, at which point they are collapsed, unread and effectively deleted by the interface rather than by anybody deciding to delete them. Approvals have the same anchoring problem and the board deliberately does NOT solve it the same way: an approval is stored against a head_oid, and dismissing it on every push is correct and is turned off by most teams within a month because it is annoying, which leaves an approval attesting to code nobody approved. Then the merge gate: requiring a branch to be up to date before merging is the only way to catch two changes that pass separately and fail together, and it serialises the entire repository - so the board adds a speculative merge queue, whose batches are held in memory by one process, and a deploy or a crash in the middle of a batch throws away every build in it and re-runs the lot.
Requirements
Ask these before drawing anything
- May the branch be rewritten, or only appended to? Append-only makes anchoring almost trivial and makes the history unreadable. Every team picks rewriting and then meets this board.
- What should happen to a comment on a line that no longer exists? There is no correct answer. Pick between "silently move it somewhere plausible" and "say it is outdated", and know that the second one means nobody reads it again.
- Does an approval survive a new push? The honest answer is no. The popular answer is yes. Decide deliberately, because the difference is whether an approval is evidence or decoration.
- Must a branch be up to date with the target before merging? Yes catches the two-changes-that-pass-separately failure and serialises the repository. No is faster and lets that failure through. This is the single biggest performance decision here.
- How many required checks, and who may make a check required? A required check with a flaky runner is a repository-wide outage with no incident channel.
- Are comments threaded, and can a thread be resolved by anyone or only by its author? This changes what "unresolved" means in the merge gate, which is the one place it has teeth.
- How long are CI logs kept? This is the entire storage bill of the product and it is usually decided by nobody.
- Is review required for every change, including reverts during an incident? The break-glass path should be designed, logged and loud - not discovered at 3am.
Functional
- Propose a change as a branch against a target, with a description and a diff.
- Comment on a specific line of a specific file, in a thread, and resolve it.
- Survive a branch update: comments follow their code where it can be found, and are marked outdated where it cannot.
- Approve or request changes, recorded against the exact head that was reviewed.
- Run required checks per head commit and report their state.
- Merge only when the gate is satisfied, with a recorded reason when it is bypassed.
Non-functional
- Diff render for a 400-file change: p95 under 1.5 s, cached thereafter.
- Re-anchoring after a push: p95 under 3 s for 50 comments, and it must be idempotent - running it twice on the same pair of heads produces the same anchors.
- A comment, once posted, is never lost. Being marked outdated is not loss; being dropped because the re-anchor threw is.
- The merge gate is evaluated from stored facts only, never from a live CI query. A gate that depends on an external service being up is an outage waiting for a deploy freeze.
- 99.9% for reading and commenting. 99.5% for merging: a blocked merge is annoying, a wrong merge is not recoverable by retrying.
Out of scope
- The version control system itself - the branch update is this board’s input.
- Running the builds. This board queues them and reads their verdicts.
- Static analysis and suggestion bots, which arrive here as ordinary comments and have the same anchoring problem in a louder voice.
The rest of this board
Available on Tier Slate
This page publishes the question. The answer — 5 more written pages, a 9-step narrated walkthrough and a 5-table schema — is the board itself, and it opens in Tierslate.
- 5written pages
- 9walkthrough steps
- 5tables42 columns
5 pages behind this one
- Capacity estimation
- Storage estimation
- Availability
- How it works
- Deployment plan
More boards
Several people editing one thing without losing an edit.