specs/015-gerrit-style-patchsets/research.md

Ref: Size: 2.7 KiB

# Research: Patch Revisions

## Decision: Revision Number Derivation

**Decision**: Derive revision numbers from topological DAG order during materialization, not store them in events.

**Rationale**: Two collaborators may independently detect the same branch change and create `PatchRevision` events concurrently. If numbers were stored, they'd conflict after DAG merge. Deriving from topo order + dedup by commit OID ensures consistent numbering post-sync.

**Alternatives considered**:
- Store revision number in event: Simpler materialization, but breaks on concurrent detection. Rejected.
- Use commit OID as revision identifier instead of numbers: Correct but poor UX — users prefer `--between 1 3` over `--between abc123 def456`. Rejected for CLI, but commit OID is the underlying identifier.

## Decision: Auto-Detection Trigger

**Decision**: Auto-detect revision changes only on write operations (comment, review, merge), never on reads (show, list, diff).

**Rationale**: Reads having side effects (appending to DAG) is surprising and requires a signing key. Write operations already require a signing key and already modify the DAG, so the incremental cost is zero.

**Alternatives considered**:
- Auto-detect on all operations including reads: Ensures revisions are always up-to-date, but side-effecting reads is an anti-pattern. Rejected.
- Explicit-only (`patch revise`): Clean but requires developer discipline. Kept as escape hatch alongside auto-detection.

## Decision: Terminology (Radicle Model)

**Decision**: Use "patch" + "revision" terminology (Radicle model), not "change" + "patch set" (Gerrit model).

**Rationale**: git-collab already uses "patch" as the top-level entity. Radicle — the closest prior art for git-native forges — also uses "patch" + "revision". Renaming to "change" would break existing CLI, events, and refs for no functional benefit.

**Alternatives considered**:
- Gerrit model ("change" + "patch set"): Would require renaming all patch commands, events, and refs. Confusing terminology ("patch set" is misleading). Rejected.

## Decision: Thread Comments Not Revision-Anchored

**Decision**: `patch.comment` events (thread comments) do not get a `revision` field. Only `patch.inline_comment` and `patch.review` are revision-anchored.

**Rationale**: Thread comments are general conversation about the patch as a whole ("looks good overall", "what's the motivation for this?"). They don't reference specific code and would gain nothing from revision anchoring. Inline comments reference file:line in a specific tree, so revision context is essential.

**Alternatives considered**:
- Anchor all events to revisions for consistency: Adds complexity without value for thread comments. Rejected.