Pull requests: a branch, named by who pushed it

Status: design, 2026-08-24. Successor to docs/plans/2026-08-21-git-collaboration.md, which built the collaboration prototype and named the Change-Id as the thing every other artifact hangs on. This replaces that decision.

What the prototype got wrong

The prototype borrowed Gerrit's Change-Id and built GitHub's branch model on top of it, then derived the change's identity from the tip commit's trailer. That combination fails in four ways, and three of them are visible.

The identity moves when a commit is added. git-remote-atproto install-hook gives every commit its own id: the hook hashes HEAD, the message, the pid and the clock. Amend the tip and the id survives. Push one more commit on top, which is how a branch is revised, and the tip's id is new. The change's id changes with it, the old address renders "No branch carries this change", and every review and check keyed to the old id detaches.

The hook and the reader disagree about what a Change-Id means. changeRun walks back from the tip while consecutive commits carry one id, so it wants one id per branch. The hook writes one id per commit. Against a real history that loop stops at the first step, and a merged pull request of eleven commits opens as its tip commit alone. It reads correctly only against scripts/dev-git-scale-demo.mjs, which seeds one id across a whole branch. No client produces that. jj does not either: jj's change ids are per commit.

A comment on a single commit page lands nowhere. The composer takes its id from the commit in view. On the third commit of a branch that is the third commit's id, not the pull request's, so the comment never joins the conversation.

Versions are a fossil record. versionsOf reconstructs earlier versions from whatever shas the checks and reviews still name. A version nobody reviewed and no runner checked never existed. There is no interdiff, and no event on the timeline for the one thing a reviewer waits for, which is the author pushing again.

What identifies a pull request

(author DID, ref). The DID of the account whose copy holds the work, and the full ref name of the branch holding it.

It survives amend, rebase, appending a commit and force-push, which is every case the trailer was bought for and one it fails. It costs nothing to compute, it needs no hook on a contributor's machine, and a push is still the whole proposal.

dev.pdsjs.git.offer already keys on it. The record is in the proposing account's own repo, so the DID is the record's owner, and it requires repo and ref. The record needs no new field to carry the identity. It only needs to drop changeId.

Two cases the pair does not cover, and what covers them:

• A branch reused for other work. Delete agent/fix, push different work under the name, and the first branch's history would attach to the second. Ancestry cannot answer this: a rebase leaves a tip the last one cannot reach and so does a name reused, and the graph shows the same thing for both. The deletion is what separates them, and the runner sees it. The push log marks the ref ended, keeps the tips it carried so a merged branch tidied away is still readable, and starts a fresh list on the next push under the name.

  What this does not fix is the reviews. They name the account and the ref, so a review of the first branch still reads as a review of the second. Closing that needs a review to name something that separates one branch of a name from the next, which no record carries today.

• A merged pull request whose branch is gone. The graph answers it where a merge commit carried the work in. Where a squash did, the merger writes the answer into the commit. See "Merging".

Versions come from the push log

The daemon is on a firehose already and every ref that moves passes through it, so it writes each tip down: a dev.pdsjs.git.versions record in its own repo, under versionsKey(did, repoName), holding one entry per ref and the tips that ref has carried, newest first.

One record per copy, not per repository. A push says nothing about which copy is canonical; the account that made it is the only thing the event carries. The reader asks for one per collaborator, all to the runner's own server.

The log is written before the run that clones and executes, so a reader asking what the author pushed does not wait on CI. A replayed event finds its tip already at the head and writes nothing.

It answers three questions that have no answer in the graph:

• the versions of a pull request, in the order they were pushed;
• what changed between any two of them;
• the timeline event "bob pushed version 2", which is the event a reviewer waits for and the one thing the graph cannot date.

A reader that cannot reach the runner unions nothing and falls back on the tips the checks and the reviews name, which is a shorter history rather than a wrong one.

An entry carries the tip and when it was seen, and no base. What that costs is the finer comparison: two versions are compared by diffing their trees, so a rebase across a moving main carries main's own changes into the answer. The screen says so rather than letting a reader take all of it for the author's work. Diffing the two patches instead needs each version's own base.

Merging

Three modes, and each leaves a different amount of the link in main's history.

mode	what main carries	what it costs
merge commit	the merge's second parent is the branch tip	nothing
squash	one commit, no edge	the merger writes a trailer
rebase	commits replayed, no edge	a trailer on each

Build merge commit first, squash second, and leave rebase out. Rebase is the rarest of the three, it needs a trailer on every commit it moves, and GitHub loses the same link in the same mode.

The trailer for a squash is written by the merger, not by the author. This is the difference that matters. Gerrit's hook runs on every contributor's machine at commit time and needs discipline from everyone who pushes. A merge trailer is written once, by the code performing the merge, at the moment the graph link would otherwise be lost. It names the identity above:

Merged-from: at://did:plc:xxx/dev.pdsjs.git.repo/pds.js
Merged-ref: refs/heads/agent/rename-ports

A merge commit carries them too. The graph already says where the work came from, and the trailers say it in the vocabulary a reader of the records speaks: an account and a ref rather than a commit id.

Both modes require the branch's merge base to be main's own tip. Then the result tree is the branch's own, there is no three-way content merge to do, and nothing about the merge can be wrong. A branch main has moved under is refused and rebasing it is the author's move.

That is the decentralised form of GitHub's (#123). GitHub recovers a squashed pull request from a number that a central authority minted. No such authority exists here, so the commit carries the answer itself.

The Change-Id, and what replaces the hook

packages/git/src/hook.js and the install-hook verb go. Contributor-side discipline was the weak part of the design and the merge trailer needs none of it.

jj writes a change-id header into the git commit object, where a reader sees it without a hook and without it appearing in the message. Tangled reads that header to trace a commit across rewrites. Reading it here too is the one piece of Change-Id worth keeping, as an optional enrichment on a version and never as the identity. It is unbuilt, and it stays a nice-to-have as long as the identity does not depend on it.

Vocabulary

The lexicons are unpublished and nothing is deployed, so the words are free to fix now and a migration later. Rename where the concept matches what a reader already knows. Keep the word where the concept differs, because a familiar word on a different concept predicts a button that is not there.

now	to
change	pull request
landed	merged
live, in flight	open
/<repo>/work	/<repo>/pulls
contributors	collaborators
dev.pdsjs.git.offer	dev.pdsjs.git.pull
verdict reject	changesRequested

reject renders as "asked for changes" in verdicts.js today, so the wire and the screen name one thing twice. The rename settles them on the screen's word, which is also GitHub's.

The offered list folds into the open list. A pull request from an account the repository has not named is marked as being from a fork and sorts with the rest, the way a forge shows one.

Two words stay:

• version, not Tangled's "round" and not Gerrit's "patch set". It is the word versionsOf already uses and it needs no glossary. GitHub has the feature and no noun for it, so there is nothing to copy.
• withdrawn, not "closed". On a forge, closed usually means the maintainer closed it. No maintainer here can, because no account is the merge authority for another. Withdrawn is the author's word about the author's own work, which is the part that is true.

ahead, behind, base and tip stay. They are git's words and a reader arrives with them.

What Tangled does

Worth recording, because it is the only other forge built under these constraints and it did not take GitHub's model.

• The pull request is a record, sh.tangled.repo.pull, in the proposing account's repo, updated as the patch changes.
• Review is round based. A submission is immutable, the first is round 0, and resubmitting advances the round. An interdiff button compares two rounds. That is Gerrit's patch sets under another name, and it is the piece worth taking.
• Change ids come from jj, as a commit header, and map a jj stack to one pull request per commit.
• Merge is fast forward, as git am applies a series. There is no squash, so the question this document answers under "Merging" does not arise for them.

Their knot holds the git data and their appview indexes it. Neither exists here, which is why the fan-in and the daemon's derived records do that work. The interop question stands where the previous document left it, a decision for before these lexicons publish.

Order to build in

1. Identity to (author DID, ref), the lexicon edits, the deletions and the vocabulary pass. Done.
2. The push log over every push. Done. dev.pdsjs.git.versions, one record per watched copy under versionsKey, written by the runner before the run that clones and executes. The reader unions it with the tips the checks and reviews name, so an unreachable runner costs history rather than accuracy.
3. The version picker, the comparison, and the push event on the timeline. Done. The comparison is a range read of <older>..<tip>, which is a diff of two trees; the bar says so, because a rebase across a moving main carries main's own changes into it. A finer comparison would diff the two patches rather than the two trees, and needs each version's own base.
4. A record from a named collaborator, so a pull request carries a title, a body and a draft state of its own. Done.
5. Merging: the merge commit, then the squash with the merger's trailer. Done. POST /account/api/git/merge, both modes, read back by git itself.

Where merging runs, and why

Not in the page. An atproto repo: scope names a collection and its actions and cannot name one record, so a page asking to write dev.pdsjs.git.repo would hold create, update and delete over every repository the account owns, in a token in IndexedDB. Merging is the authority's own act, so it runs on the authority's own server under the session cookie the account page already answers to. The repository browser reaches it because the browser is served from that account's site.

createGitMerger is the seam. The pack format belongs to @pdsjs/git and the authority over the record belongs to the PDS, so the platform builds the merger out of storage it owns and injects it, the way it already builds the write guard. Core carries no dependency on the git package.

The write goes through the ordinary commit path, so the guard sees a merge and a protected branch still refuses anything but a fast-forward. The new bundle carries a pack index, so the chain stays readable through ranged reads.

What a branch has to be to merge. Its merge base must be main's own tip. Then the result tree is the branch's own, and there is nothing about the merge to get wrong. A branch main has moved under is told to rebase, rather than offered a button that cannot work. A three-way content merge would lift that and is a build of its own.

A merge carries the tree of every commit it makes reachable, not the tip's alone. Git walks every commit the merge reaches and opens each one's tree, so a tree left out fails the whole fetch. Driving the endpoint against a real stack is what found this; the unit tests had passed because their branches were one commit deep.

Steps 1 and 2 carry the design. Everything after is what a reader sees for it.