From 7a6169705a7bf326dfd8c0184fbf0fb5259da2d6 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Wed, 29 Apr 2026 12:57:44 +0200 Subject: [PATCH] docs: lock in fork stance, reframe cherry-pick list as reference-only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After attempting cluster B (4 surgical agent-session fixes), even the first commit conflicted because of structural namespace divergence (gsd_*→sf_* rename, @sf-run/*→@singularity-forge/* rename, prior pi-mono direct cherry-picks). The conflicts are real semantic divergence, not noise. Conclusion: sf is a fork; we do not periodically sync from gsd-build/gsd-2. Pretending we still track upstream means weeks of merge work for diminishing return. BUILD_PLAN.md adds an explicit "Upstream stance" section documenting the fork posture and the rationale for the three irreversible naming choices. UPSTREAM_CHERRY_PICK_CANDIDATES.md is reframed as a reference list, not an action plan. The clusters and SHAs remain useful as an intelligence source — port specific fixes by hand when one bites us; do not run automated cherry-picks against the list. Pi-mono SDK syncs continue separately — that path doesn't have the same divergence problem. Co-Authored-By: Claude Sonnet 4.6 --- BUILD_PLAN.md | 20 ++++++++++++++++++++ UPSTREAM_CHERRY_PICK_CANDIDATES.md | 12 ++++++++---- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/BUILD_PLAN.md b/BUILD_PLAN.md index 24c84df3e..b2dff1d1c 100644 --- a/BUILD_PLAN.md +++ b/BUILD_PLAN.md @@ -8,6 +8,26 @@ It is opinionated. Each item has a tier and a one-line rationale. Reorder freely --- +## Upstream stance + +**sf is a fork.** We do not periodically sync from `gsd-build/gsd-2`. + +We tried (see attempt log in `UPSTREAM_CHERRY_PICK_CANDIDATES.md`). The conflicts run deep because of three structural choices that are intentional and won't be reverted: + +- We renamed `gsd_*` tool names → `sf_*` (`421fccd89`). +- We renamed `@sf-run/*` → `@singularity-forge/*` package scope (`f92ee8d64`). +- We've cherry-picked tool fixes from `pi-mono` upstream directly (`f153521c2`), which addresses some bugs that `gsd-2` fixed differently. + +Pretending we still track gsd-2 means weeks of merge work for diminishing return. Better to: + +- **Treat `gsd-build/gsd-2` upstream as an intelligence source.** We read it. We hand-port fixes when one specifically bites us. `UPSTREAM_CHERRY_PICK_CANDIDATES.md` is a reference list of what's available, not an action plan. +- **Pull from `pi-mono` directly for SDK improvements.** We've already been doing this; continue. +- **Track our own roadmap** via `SPEC.md` and this file. + +If a specific upstream fix matters (e.g. a CVE, a bug we hit), port it manually and credit upstream in the commit message. Don't try to sync the whole tree. + +--- + ## Tier 1 — ESSENTIAL (block v3 ship) These resolve real product or correctness gaps. v3 isn't v3 without them. diff --git a/UPSTREAM_CHERRY_PICK_CANDIDATES.md b/UPSTREAM_CHERRY_PICK_CANDIDATES.md index e10faa4f0..b2949a499 100644 --- a/UPSTREAM_CHERRY_PICK_CANDIDATES.md +++ b/UPSTREAM_CHERRY_PICK_CANDIDATES.md @@ -1,10 +1,14 @@ -# Upstream cherry-pick candidates +# Upstream reference list (NOT a cherry-pick action plan) -A read-only enumeration of high-value commits in `gsd-build/gsd-2` (`upstream/main` at `fec206dda`, 2026-04-28) that are not in `singularity-ng/singularity-foundry/main` (at `b24f426f2`, 2026-04-29). +> **Status: REFERENCE.** sf is a fork; we do not sync from `gsd-build/gsd-2`. See [`BUILD_PLAN.md`](./BUILD_PLAN.md) §"Upstream stance" for why. This file is preserved as **an intelligence list** — high-value upstream work to read or hand-port if a specific bug or feature warrants it. Do not run `git cherry-pick` against this list; the rename divergence (`gsd_*`→`sf_*`, `@sf-run/*`→`@singularity-forge/*`, partial pi-mono cherry-picks) makes automated picks conflict on virtually every commit. +> +> **An attempt was made and rolled back:** cluster B's first commit conflicted on `agent-session.ts` and a deleted test file. Aborted clean. The conflicts were semantic (real divergence), not whitespace. -Total upstream-only commits: 4,589. This list is the **high-leverage subset** worth cherry-picking. Skipping the bulk of small/internal commits. +A read-only enumeration of notable commits in `gsd-build/gsd-2` (`upstream/main` at `fec206dda`, 2026-04-28) that are not in `singularity-ng/singularity-foundry/main` (at `b24f426f2`, 2026-04-29). -Clusters are roughly ordered by "take this first." Each cluster lists candidate SHAs with one-line context. +Total upstream-only commits: 4,589. This list is the **high-leverage subset** worth being aware of. Skipping the bulk of small/internal commits. + +Clusters are roughly ordered by "if any port is worth doing, this first." Each cluster lists SHAs with one-line context. ---