Tracelab Public Release

TraceLab Public Release

Purpose

Publish curated TraceLab snapshots from the internal repository to the public repository:

https://github.com/uw-syfi/TraceLab.git

as incremental, mergeable pull requests that preserve git ancestry, so every release shows only its true net diff and can be merged without conflicts. Do not push snapshots directly to the public main; open a (draft) PR for review.

Mental model — why ancestry matters

The public repo must always be reachable as an ancestor of the branch you open the PR from. When that holds, GitHub's PR diff (merge-base...head) equals the real net change and the PR merges cleanly. When it does not, git falls back to an ancient common ancestor and reports phantom conflicts — add/add on every new file and content conflicts on every edited file — even though the branch is a clean superset of what the public repo already has.

This is exactly what the old "export to a temp dir, wipe a clean clone of public, copy the export, commit one snapshot" method caused: each release landed in public as a detached snapshot commit with no shared history with the source branch. The next fork→public PR then diffed against the last truly shared commit (e.g. an early Merge PR #1), surfacing hundreds of files that were never actually in conflict. Do not publish by wipe-and-snapshot anymore. Publish from a persistent mirror whose history stays linked to public.

Remotes

The mirror branch (the fork's main; commonly checked out locally as fork-main) is the public-safe history. Keep it linked to public/main.

Guardrails

1. Treat origin as the internal/source-of-truth remote unless the user says otherwise.
2. Never push to the public main. Push only to the fork mirror (its main or a release branch) and open a PR into public:main.
3. Keep public/main an ancestor of the branch you open the PR from. Reconcile first (below) whenever it is not — never open a PR that GitHub reports as conflicting.
4. Do not commit trace data to Git. Release data files belong only on GitHub Releases. Keep ignored/local files such as trace/*.jsonl*, trace/*.duckdb, trace.tar.gz, generated artifact outputs, and server runtime data out of the public tree.
5. When a reconciling merge conflicts, resolve in favor of the mirror for content the mirror has advanced — but first confirm no genuine public-only commit (community PR, hotfix) or public-only file is being dropped.
6. Preserve the web product title SyFI Trace Atlas unless the user explicitly asks to rename it.
7. Do not put dates in PR titles or branch names. Name the branch after the actual release theme.

Release workflow

1. Sync and inspect

git fetch public
git fetch fork
git status --short --branch
git remote -v

Add the public/fork remotes if missing:

git remote add public https://github.com/uw-syfi/TraceLab.git
git remote add fork   https://github.com/serendipity-zk/TraceLab.git

2. Land intentional changes on the mirror

Check out the mirror branch (e.g. fork-main) and make sure every change you intend to publish is committed there. Do not try to snapshot a dirty worktree — commit the intentional source/doc changes first, and leave ignored trace data and generated outputs uncommitted.

3. Re-link ancestry (the key step)

Make public/main an ancestor of the mirror by merging it in:

git merge --no-ff public/main

• If public/main is already an ancestor, this is a no-op or fast-forward — skip to step 4.

• If it conflicts, the conflicts are almost certainly phantom (public holds an older copy of the same lineage from a prior snapshot release). Confirm the mirror is the newer superset and resolve every conflict to the mirror, then verify nothing real was dropped:

  # see why each side diverged — public's version should be a subset of the mirror's
  git diff <merge-base> public/main -- <file>     # what the public snapshot changed
  git diff <merge-base> fork-main  -- <file>      # what the mirror changed (should subsume it)
  
  # resolve all conflicts to the mirror
  for f in $(git diff --name-only --diff-filter=U); do git checkout --ours -- "$f" && git add -- "$f"; done
  
  # SAFETY: no files exist only in public, and no non-export public commits are being skipped
  comm -23 <(git ls-tree -r --name-only public/main | sort) <(git ls-tree -r --name-only fork-main | sort)
  git log --oneline <merge-base>..public/main      # every entry should be an export/snapshot, not a community PR

  If a real public-only file or community commit exists, stop and merge it into the mirror properly instead of discarding it. Otherwise commit the reconciling merge:

  git commit --no-edit

Verify ancestry is now linked and the PR will be clean:

git merge-base --is-ancestor public/main fork-main && echo linked
git diff --name-only public/main...fork-main | wc -l   # three-dot (what GitHub shows)
git diff --name-only public/main    fork-main | wc -l   # two-dot (true delta) — must match