Tracking: adopt the proposed development model

[krystophny]

Umbrella for the proposed development model (docs/development-model.md,
PR #54). For group discussion on Discord before adoption.

Done in PR #54:

• Relocate infra to $CODE/infra; external workspace-shared at $CODE/external
• Retire the umbrella build-everything CI (main.yml)
• Design note + workflow templates (docs/templates/)

Remaining:

• Standardize <DEP>_BRANCH across consumers (Standardize <DEP>_BRANCH override across libneo consumers #55)
• libneo release workflow + downstream gate (Release workflow: release branch + downstream reverse-dependency gate libneo#277)
• Add integration.yml to each consumer (template: docs/templates/downstream-integration.yml)
• Adopt YY.MINOR.PATCH, tag-derived, no leading zeros, across the codes
• Decide setup.yml fate (Decide fate of setup.yml (release-tarball builder) #56)

Model in one line: a self-describing find_or_fetch graph, per-code CI at the
source, and release-time reverse-dependency validation owned by the upstream.

[krystophny]

Automated triage pass (Claude), grounded in the repository at 07d67ba. Verify before acting.

Still open and still the right umbrella, but the checklist is now out of date in both directions: three of the five remaining items have effectively landed in the consumer repos under different names and mechanisms, while the item that silently blocks everything — merging PR #54 itself — is not on the list at all. This comment re-derives the ledger from the actual repos.

Purpose

The development model exists so that a breaking change in libneo surfaces in the pull request that caused it, rather than in a downstream code weeks later, and so that a published NEO-2/SIMPLE/MEPHIT result can be reproduced from a single version string. The old umbrella CI could not deliver this — it built the unpinned tips of six repos in one sequential job and never passed (docs/development-model.md:42-46, "Integration testing": "It never passed (0 of 94 runs)"). Half the replacement is now live; the tracker should reflect that and drive the rest home.

Current state

PR #54 is unmerged. main has not moved since 2026-01-15.

$ git -C code rev-list --left-right --count main...origin/chore/relocate-infra
0	8
$ git -C code log -1 --format='%h %ad' --date=short main
07d67ba 2026-01-15
$ git -C code log -1 --format='%h %ad' --date=short origin/chore/relocate-infra
575bf89 2026-07-09

Consequences on main today: docs/ does not exist, so docs/development-model.md and docs/templates/*.yml are unreachable to anyone reading the repo; .github/workflows/main.yml is still present and still triggers on push and pull_request to main; the libneo and SIMPLE gitlinks are still in the tree (160000 commit d3ecd23… and 8483ed8…). The branch is 0 commits behind, so nothing blocks the merge technically.

Item: <DEP>_BRANCH across consumers (#55) — done, but renamed and uneven.

The convention shipped as <DEP>_REF, not <DEP>_BRANCH. All six consumers accept it:

• NEO-RT/cmake/Util.cmake:14 — the reference implementation and the only one with the full three-rung ladder (<DEP>_REF → <DEP>_RELEASE → current branch else main), with git ls-remote validation and a warning on a bad ref.
• NEO-2/cmake/Util.cmake:13 (${DEPENDENCY_UPPER}_REF), MEPHIT/cmake/Util.cmake:12 and KAMEL/cmake/Util.cmake:18 (${_DEP_UPPER}_REF) — rungs 1 and 3 only, no _RELEASE rung.
• SIMPLE/cmake/Util.cmake:77 — hardcoded LIBNEO_REF, not generalised; it does validate against the remote (SIMPLE/cmake/Util.cmake:82-94) but find_or_fetch FATAL_ERRORs on any dependency other than libneo (SIMPLE/cmake/Util.cmake:113).
• rabe/cmake/libneo.cmake:7 — bespoke rabe_add_libneo(), not find_or_fetch; falls back to a hardcoded SHA 54e372f2ef15cf6cf0f36d734500c64d10cd5ada (rabe/cmake/libneo.cmake:29).

Five of six keep a local-path shortcut, which docs/development-model.md:31 explicitly forbids ("There is no local-path shortcut: a sibling checkout is not consulted"). Only NEO-RT is clean:

repo	file:line	variable
NEO-2	NEO-2/cmake/Util.cmake:6	${DEPENDENCY}_SOURCE_DIR
MEPHIT	MEPHIT/cmake/Util.cmake:6	${_DEP_UPPER}_PATH
KAMEL	KAMEL/cmake/Util.cmake:12	${_DEP_UPPER}_PATH
SIMPLE	SIMPLE/cmake/Util.cmake:52-70	${_dep_upper}_SOURCE_DIR (_use_local)
rabe	rabe/cmake/libneo.cmake:4,22	LIBNEO_PATH
NEO-RT	—	none

Item: integration.yml in each consumer — the checklist wording is stale; the substance shipped.

No repo has an integration.yml and none needs one. Every consumer's existing workflow accepts a libneo_ref dispatch input, and each maps it onto the resolver override:

repo	workflow input	override site
SIMPLE	.github/workflows/main.yml:10	main.yml:85, :172
NEO-2	.github/workflows/unit-tests.yml:15	unit-tests.yml:74
MEPHIT	.github/workflows/main.yml:16	main.yml:39
KAMEL	.github/workflows/ci.yml:10	ci.yml:60
rabe	.github/workflows/test.yml:9, golden.yml:9	test.yml:27-28 (via nix develop)
NEO-RT	.github/workflows/test.yml:13	test.yml:41

Note: docs/templates/downstream-integration.yml is not a dead template. Commit be6a7c0 already rewrote it into a snippet that documents exactly this mechanism — its own header reads "There is no separate integration workflow. Add these three pieces to the downstream's existing CI workflow." It should be kept. Only the issue checklist line ("Add integration.yml to each consumer") is stale.

Item: libneo release workflow + downstream gate (libneo#277) — half done, and the delivered half is a different design.

libneo/.github/workflows/downstream-gate.yml (from 08e6bd5, "Per-PR reverse-dependency gate against downstream codes (#278)") gates on every libneo PR, not at release time. The gated set is data, in libneo/ci/downstreams:

SIMPLE   main.yml         yes   yes
NEO-2    unit-tests.yml   yes   no
MEPHIT   main.yml         yes   yes
KAMEL    ci.yml           yes   yes
rabe     test.yml         yes   golden.yml
NEO-RT   test.yml         no    no

Per-PR gating is strictly stronger than the release-time gate the doc describes, and the doc has not been updated to say so. What is still missing is the release side: libneo/.github/workflows/ contains only main.yml and downstream-gate.yml, and neither release/downstreams nor release/check-downstreams.sh (named in the libneo#277 discussion and at docs/development-model.md:99) exists at fe3f76e.

Item: YY.MINOR.PATCH CalVer — not adopted anywhere.

• libneo tags are YYYY.MM.DD, not YY.MINOR.PATCH: most recently v2025.07.29, v2025.07.30, v2025.11.25, v2026.04.13, v2026.07.01 (plus legacy v0.0.3, v1.0.0).
• SIMPLE tags: v1.4.2, v1.5.0, v1.5.1 — SemVer; its release branches are release/1.5, not release/26.N.
• libneo/pyproject.toml:11 is version = "0.0.3", hardcoded; no setuptools_scm. libneo/CMakeLists.txt:23 is project(libneo) with no VERSION.
• Rung 2 of the ladder is dead: rg -n 'LIBNEO_RELEASE|\}_RELEASE' across the cmake/ trees of libneo, SIMPLE, NEO-2, NEO-RT, MEPHIT, KAMEL and rabe matches only the reader at NEO-RT/cmake/Util.cmake:35-36. Nothing sets it.
• libneo does have origin/release/26.2, but its tip is 43edb34 (2026-06-08) while main is fe3f76e (2026-07-16), and no consumer tracks it.

Item: setup.yml fate (#56) — undecided. .github/workflows/setup.yml exists on both main and the branch, still triggers on tags v* (setup.yml:3-6), and code has had no tag since v2025.06.03.

Reproduction / evidence

These are static checks — no network, no configure needed.

Rung 2 is unreachable in five of six consumers. Only NEO-RT reads _RELEASE:

cd $CODE && rg -n 'LIBNEO_RELEASE|\}_RELEASE' \
  {libneo,SIMPLE,NEO-2,NEO-RT,MEPHIT,KAMEL,rabe}/cmake/*.cmake
# observed: NEO-RT/cmake/Util.cmake:35 and :36 only
# (a bare '_RELEASE' pattern is noisy — it hits CMAKE_Fortran_FLAGS_RELEASE
#  and LSB_RELEASE_EXECUTABLE in FindSuiteSparse.cmake)

The forbidden local-path escape hatch, in five of six:

cd $CODE && rg -n '_use_local|_PATH AND EXISTS|LIBNEO_PATH|if\(\$\{DEPENDENCY\}_SOURCE_DIR\)' \
  {SIMPLE,NEO-2,NEO-RT,MEPHIT,KAMEL,rabe}/cmake/*.cmake
# observed: SIMPLE:50,58,64  NEO-2:6  MEPHIT:6  KAMEL:11,12  rabe:3,4,22,23,24
# NEO-RT: no match (its :57 ${DEPENDENCY}_SOURCE_DIR is the FetchContent-populated
# dir, not a local-checkout shortcut)

Configure-time confirmation (needs network, since every path calls git ls-remote). NEO-2 prints branch, not ref, when only LIBNEO_RELEASE is given, because NEO-2/cmake/Util.cmake:16-18 falls straight through to get_branch_or_main:

cd NEO-2 && cmake -S . -B /tmp/b -DLIBNEO_RELEASE=release/26.2 2>&1 | grep 'Using libneo'
# expected from the source: "Using libneo branch main from https://github.com/itpplasma/libneo.git"
# expected under the model:  "Using libneo ref release/26.2 ..."

cd NEO-2 && cmake -S . -B /tmp/b -DLIBNEO_REF=release/26.2 2>&1 | grep 'Using libneo'
# expected: "Using libneo ref release/26.2 from https://github.com/itpplasma/libneo.git"

Behaviour (BDD)

Scenario: Every consumer honours the committed release pin
  Given NEO-2, SIMPLE, MEPHIT, KAMEL and rabe declare LIBNEO_RELEASE=release/26.2 as a committed cache variable
  When "cmake -S . -B build" runs with no -DLIBNEO_REF
  Then the configure log prints "Using libneo ref release/26.2"
  And no configure reads a sibling checkout under $CODE

Scenario: Upstream candidate overrides the pin
  Given libneo has cut branch release/26.3
  When each consumer is configured with -DLIBNEO_REF=release/26.3
  Then the configure log prints "Using libneo ref release/26.3"
  And the committed LIBNEO_RELEASE value is unchanged in the working tree

Scenario: The local-path shortcut is gone
  Given NEO-2 is configured with -Dlibneo_SOURCE_DIR=$CODE/libneo
  When "cmake -S . -B build" runs
  Then the configure log does not contain "Using local libneo"
  And the configure log contains "Using libneo ref"

Scenario: Release gate blocks a tag on a red downstream
  Given libneo/ci/downstreams lists "SIMPLE main.yml yes yes"
  And SIMPLE's dispatched run against the candidate concludes "failure"
  When libneo's release workflow runs for release/26.3
  Then no tag v26.3.0 is created
  And the workflow annotates "::error::SIMPLE CI red against libneo release/26.3"

Scenario: Version string agrees across git, CMake and PEP 440
  Given libneo is checked out at tag v26.3.0
  When "python -c 'import importlib.metadata as m; print(m.version(\"libneo\"))'" runs after a pip install
  Then the output is exactly "26.3.0"
  And "cmake -S . -B build" reports libneo project VERSION 26.3.0

Scenario: main.yml no longer runs on the meta-repo
  Given PR #54 is merged into itpplasma/code main
  When a commit is pushed to main
  Then .github/workflows/main.yml does not exist
  And docs/development-model.md is readable on main

Implementation plan

Ordered; steps 2–5 depend on step 1 landing so there is a canonical document to point at.

1. itpplasma/code, PR Relocate infra to $CODE/infra; keep $CODE as the workspace root #54. Merge chore/relocate-infra into main. Two edits to docs/development-model.md on that branch first — and note that the <DEP>_BRANCH → <DEP>_REF rename and the "no local-path shortcut" rule are already fully applied by be6a7c0 (there is no remaining _BRANCH occurrence in the file), so do not redo them:
   • Rewrite ## Integration testing (lines 40-57) so layer 2 is the per-PR gate that shipped in libneo 08e6bd5, with release-time dispatch as layer 3.
   • Line 99 says the gate reads release/downstreams; the shipped file is ci/downstreams. Fix the name.
   • Line 3: replace Status: proposed, 2026-05. Open for group discussion before adoption. with Status: adopted, <date>.
   • Keep both templates. docs/templates/downstream-integration.yml already documents the shipped snippet approach and stays.
2. itpplasma/SIMPLE, cmake/Util.cmake. Replace the libneo-only body of find_or_fetch (lines 45–114) with the generic three-rung implementation from NEO-RT/cmake/Util.cmake:14-63, and delete the _use_local local-path branch (lines 49–70). Keep set(LIBNEO_ENABLE_TESTS OFF CACHE BOOL "" FORCE). SIMPLE already defines its own get_branch_or_main at line 3; keep exactly one definition.
3. itpplasma/rabe. Replace the bespoke rabe_add_libneo() in cmake/libneo.cmake with the find_or_fetch from NEO-RT (copy to rabe/cmake/Util.cmake). The include site is rabe/src/vmec/CMakeLists.txt:5 (include(libneo)), not the top-level CMakeLists.txt — rabe/CMakeLists.txt:7 only puts cmake/ on CMAKE_MODULE_PATH. Drop LIBNEO_PATH and the hardcoded SHA in favour of LIBNEO_RELEASE. Preserve the -w warning suppression (lines 19-20) and LIBNEO_BUILD_NUMERICS OFF (line 11).
4. itpplasma/{NEO-2,MEPHIT,KAMEL}, cmake/Util.cmake. Two changes each. Do not copy NEO-RT lines verbatim: NEO-RT uses _DEP/_ref, these three use REMOTE_BRANCH and differing uppercase variables.
   • Add rung 2 between the _REF test and get_branch_or_main.
     NEO-2 (variable is DEPENDENCY_UPPER), insert before line 16's else():

     elseif(DEFINED ${DEPENDENCY_UPPER}_RELEASE AND NOT "${${DEPENDENCY_UPPER}_RELEASE}" STREQUAL "")
         set(REMOTE_BRANCH "${${DEPENDENCY_UPPER}_RELEASE}")
         message(STATUS "Using ${DEPENDENCY} ref ${REMOTE_BRANCH} from ${REPO_URL}")

     MEPHIT (before line 14's else()) and KAMEL (before line 20's else()), variable is _DEP_UPPER:

     elseif(DEFINED ${_DEP_UPPER}_RELEASE AND NOT "${${_DEP_UPPER}_RELEASE}" STREQUAL "")
         set(REMOTE_BRANCH "${${_DEP_UPPER}_RELEASE}")

   • Delete the local-path branch: NEO-2/cmake/Util.cmake:6-8, MEPHIT/cmake/Util.cmake:6-9, KAMEL/cmake/Util.cmake:12-15, unwrapping the else() body in each.
   • Also add set(LIBNEO_RELEASE release/26.N CACHE STRING "libneo release branch this code tracks") to each repo's top-level CMakeLists.txt, all naming the same branch.
5. itpplasma/libneo. (a) pyproject.toml:11: replace version = "0.0.3" with dynamic = ["version"] plus a [tool.setuptools_scm] section, and add setuptools_scm to build-system.requires (lines 2-6, currently scikit-build-core, numpy, f90wrap). (b) CMakeLists.txt:23: project(libneo VERSION ...) fed from the same tag. (c) New .github/workflows/release.yml from code's docs/templates/upstream-release.yml: cut release/YY.MINOR, dispatch each blocking row of ci/downstreams with libneo_ref=release/YY.MINOR, reuse the await_run (downstream-gate.yml:69) and run_wf (:109) helpers — factor them into ci/lib/dispatch.sh sourced by both rather than duplicating — gate the tag on all-green, tag YY.MINOR.PATCH, then open bump PRs setting LIBNEO_RELEASE in each consumer. Close libneo#277 with that PR.
6. itpplasma/code, .github/workflows/setup.yml. Resolve Decide fate of setup.yml (release-tarball builder) #56: either delete it, or update its pushd external step (line 83) for the relocated $CODE/external layout and keep it as the devcontainer prebuilt bundle. Do not leave it triggering on v* in an inconsistent state.
7. Tests. Add libneo/test/ci/test_downstreams_table.sh asserting every row of ci/downstreams names a workflow file that exists in that repo's default branch and declares a libneo_ref input (skipped without a token). Add to each consumer a configure-only CI job that runs cmake -S . -B build-refcheck -DLIBNEO_REF=<sha> and greps the Using libneo ref line, so a ladder regression is caught without a full build.
8. This issue. Retitle to the remaining scope and replace the body checklist with the ledger above. Steps 2–4 are independent one-repo PRs; open them as atomic issues in each consumer repo and link them here.

Acceptance criteria

• PR Relocate infra to $CODE/infra; keep $CODE as the workspace root #54 merged; git -C code ls-files docs/development-model.md non-empty on main and .github/workflows/main.yml absent.
• rg -n '_use_local|_PATH AND EXISTS|LIBNEO_PATH|if\(\$\{DEPENDENCY\}_SOURCE_DIR\)' {SIMPLE,NEO-2,NEO-RT,MEPHIT,KAMEL,rabe}/cmake/*.cmake returns nothing.
• Each of SIMPLE, NEO-2, NEO-RT, MEPHIT, KAMEL, rabe resolves refs in the order <DEP>_REF → <DEP>_RELEASE → current-branch-else-main, and each prints the single line Using <dep> ref <ref> from <url>.
• rg -n 'set\(LIBNEO_RELEASE' matches in all six consumers, all naming the same libneo release branch.
• Configuring each consumer with -DLIBNEO_REF=<sha> prints Using libneo ref <sha>; with no override it prints the LIBNEO_RELEASE value.
• libneo release run for a candidate branch dispatches all five blocking rows of ci/downstreams, fails without tagging if any is red, and produces tag v26.N.0 on all-green.
• pip install libneo at tag v26.N.0 reports metadata version 26.N.0 (no leading zeros, PEP 440 clean).
• downstream-gate.yml still green on a no-op libneo PR after the ci/lib/dispatch.sh refactor.
• Standardize <DEP>_BRANCH override across libneo consumers #55, Decide fate of setup.yml (release-tarball builder) #56 and libneo#277 closed with references to the merging PRs.

References

• PEP 440, Version Identification and Dependency Specification (Coghlan & Stufft, 2013) — the normalisation rule (26.05 → 26.5) that docs/development-model.md:120-123 cites for the no-leading-zeros constraint.
• setuptools_scm — the tag-as-single-source-of-truth mechanism named at docs/development-model.md:117.
• CalVer precedent as cited in the doc itself (docs/development-model.md:132-133): GROMACS (2026.2) and FEniCS (2019.1.0).
• CMake FetchContent (GIT_TAG accepts a branch, tag or commit) is the mechanism all six find_or_fetch variants build on.
• The release-gate design (upstream dispatches downstream CI and blocks on green) has no specific literature reference; it is an implementation detail internal to the org.

Scope and risk

Not a single PR: step 1 is one merge in code, steps 2–4 are five independent small consumer PRs, step 5 is a substantial libneo PR, step 6 is a decision. The main risk is step 5(a): switching libneo to setuptools_scm changes the wheel version seen by pip install --no-build-isolation -e . in code/scripts/setup/libneo.sh:15 and by the devcontainer image, so it should land on its own and be smoke-tested against scripts/setup.sh before the first CalVer tag. Step 3 is the riskiest consumer change — rabe pins a SHA and builds through nix develop .#default --command make (rabe/.github/workflows/test.yml:28), the only consumer not invoking make directly.

Cross-links: #55, #56, itpplasma/libneo#277, PR #54, libneo#278 (merged as 08e6bd5).