open/playground-design-system
1
0
Fork 0
Code Issues Releases 1 Activity

docs(vendoring): name what source becomes, and why push must precede re-sync

Browse source 
The doc argued that the first real re-sync is what makes source_commit
truthful, but never said what the restored script actually writes: source is
the repo name (not a path, not a machine-local absolute path) and source_commit
is git rev-parse HEAD in the source checkout.

Naming the second half makes an ordering constraint visible that was implicit:
a re-sync run before this repo's commit reaches the public mirror stamps two
public consumer repos with a hash that exists on one machine. That is the
c1b7bad defect again with a fresher date, so the check to run first is written
out.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-27 00:49:46 +02:00
commit efaa3d0e79
1 changed files with 11 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/vendoring-and-re-sync.md
View file

@ -120,6 +120,17 @@ re-sync, and let the script write a truthful manifest in which `source_commit`
is this repo's `HEAD` — reachable from this repo, unlike `c1b7bad`. Until then,
a visibly stale field is the more honest state.
Concretely, the restored script writes `source: "playground-design-system"` —
the repo name, not a path inside it and not the absolute path of whatever
checkout happened to be read, since either would be a machine-local string in a
committed file. `source_commit` comes from `git rev-parse HEAD` in the source
checkout. **That makes the push order load-bearing: run the first re-sync only
after this repo's commit is on the public mirror**, or the manifest gets a hash
that exists on one machine — the same unreachable-pointer defect as `c1b7bad`,
with a fresher date on it. Check with
`git -C <this repo> rev-parse HEAD` against `git -C <this repo> rev-parse origin/main`
before syncing.
One correction to the premise this question arrived with: the lineage is **not**
severed. `c1b7bad` is unreachable from this repo and from either consumer, but
it is alive in `catalog`. "Nobody can compute how far behind a vendored copy is"