singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: lock in fork stance, reframe cherry-pick list as reference-only

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Mikael Hugo 2026-04-29 12:57:44 +02:00
parent a80beb83b5
commit 7a6169705a
2 changed files with 28 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
BUILD_PLAN.md
View file

@ -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.

12
UPSTREAM_CHERRY_PICK_CANDIDATES.md
View file

@ -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.
---