cellpy v2.0 — consumer upgrade on cellpy-core

[jepegit]

Summary

Parent epic for cellpy v2.0: the consumer-side upgrade that builds on the finished v1→cellpy-core integration. cellpy keeps loaders, plotting, batch, CLI, and HDF5 — but adopts keyed per-test metadata, thins CellpyCell to orchestration, and retires legacy duplication.

Planning doc (source of truth): .issueflows/04-designs-and-guides/cellpy-v2-epic.md

Companion docs live in the cellpy-core repo under .issueflows/04-designs-and-guides/ (integration strategy, migration guide, metadata model).

Goal

Ship cellpy v2.0 as a behaviour-compatible upgrade where CellpyCell orchestrates cellpy-core, supports merged multi-test campaigns via test_id + TestMetaCollection, simplifies the public API, and enforces parity through tests — not vigilance.

Gate (Phase 0 — must complete before v2 feature work)

• Bump pinned cellpy-core to the polars engine and verify end-to-end parity #384 — Bump/sync pinned cellpy-core and verify end-to-end parity (closed 2026-07-14; superseded by Prepare cellpy to consume cellpy-core (isolate the Data object via a core seam) #377, Add header/unit parity contract tests between cellpy and cellpy-core #378, Stage 0.7: Value-parity comparator — the mapped-columns oracle harness #434 + PyPI cellpycore==0.1.5)
• Decommission cellpy's in-repo legacy step/summary engine now that it delegates to cellpy-core #385 — Decommission in-repo legacy step/summary engine
• STEP-12 (cellpy) — Delegate unit converters to cellpycore.units
• Close cellpy core alignement #387 when gate is green; close isolate parts needed for cellpy-core #334 as superseded by Prepare cellpy to consume cellpy-core (isolate the Data object via a core seam) #377

Epic phases (child issues to be carved out)

Phase	Focus	Theme IDs
1	Data model: TestMetaCollection, per-test cycle_mode, v1 compat	V2-01 … V2-04
2	Loaders + harmonized raw + multi-file merge	V2-05 … V2-08
3	Thin CellpyCell, public API cleanup, native schema opt-in	V2-09 … V2-12
4	HDF5 v2, metadata persistence, release pin + migration guide	V2-13 … V2-15

Proposed child issues (not yet filed)

Slug	Themes	Blocks
v2-gate-parity-and-legacy-cleanup	Phase 0	everything
v2-testmeta-on-data	V2-01, V2-02, V2-04	merge, loaders
v2-composite-keys-merge	V2-03, V2-07	release
v2-loader-harmonized-raw	V2-05, V2-06, V2-08	merge
v2-slim-cellpycell-api	V2-09, V2-10, V2-12	release
v2-file-format-and-persistence	V2-13, V2-14, V2-15	v2.0 tag
v2-native-schema-opt-in	V2-11	optional

Prerequisites already done (integration roadmap)

• Prepare cellpy to consume cellpy-core (isolate the Data object via a core seam) #377 — Core seam on OldCellpyCellCore
• Add header/unit parity contract tests between cellpy and cellpy-core #378 — Header/unit contract tests
• Bump pinned cellpy-core to the polars engine and verify end-to-end parity #384 — Pin + parity smoke (closed; essential suite + Arbin goldens green on cellpycore==0.1.5)
• Stage 0.7: Value-parity comparator — the mapped-columns oracle harness #434 — Value-parity oracle (assert_value_parity)
• cellpycore>=0.1.2 on PyPI; editable path for local dev
• Core: metadata scaffolding (Update coverage to 4.3.4 #37), test_id in schemas (Update coverage to 4.4 #41), polars engine (Tutorial  #13)

Parallel hardening (cellpy-core)

• Selectors: port remaining functions to native schema or make bridge-only cellpy/cellpy-core#67 — Selectors: native port or bridge-only
• Units fallback: replace crashing data.<attr> fallback with explicit values or CellMeta cellpy/cellpy-core#68 — Units: explicit values / CellMeta API
• Design pass: schema-agnostic step-stat columns (B1) and cycle_mode default polarity (B2) cellpy/cellpy-core#70 — Engine contract docs + cycle_mode default polarity

Success criteria (v2.0 release)

See the epic doc checklist. Key points: no dual compute engine, merged campaigns work with composite (test_id, cycle_num, step_num, …) keys, v1 files load with test_id=0, exact cellpycore== pin at release.

Non-goals

• Rewriting plot/batch/CLI
• Engine re-port (lives in cellpy-core)
• Merging branch 334
• Requiring populated metadata on core's hot path

[jepegit]

Branching conventions (agreed)

v2 epic work uses a long-lived v2 branch; master stays the 1.x line for other contributors.

Work	PR target
Epic #402 and child issues (V2-01 … V2-15)	v2
Bugfixes, general 1.x features	master
Phase 0 gate (#384, #385)	master if parity tests show no behaviour change

Docs (on master and v2):

• .issueflows/04-designs-and-guides/cellpy-v2-branching.md — full conventions
• .issueflows/04-designs-and-guides/cellpy-v2-epic.md — epic scope + phases
• .issueflows/04-designs-and-guides/cellpy-v2-architecture.excalidraw — architecture diagram

Remote branch: origin/v2 is now pushed (forked from current master).

When carving child issues, add Target branch: v2 and label v2 unless the work is explicitly 1.x maintenance.

[jepegit]

GitHub setup completed:

• Label v2 created (purple) — applied to this issue
• Branch protection on master and v2:
  • PR required before merge (0 approvals)
  • Required CI: Run pytest on linux (conda), Installing using pip on posix
  • Strict up-to-date; no force-push / branch delete
  • Admins can bypass for emergencies

Details in `.issueflows/04-designs-and-guides/cellpy-v2-branching.md` (GitHub hygiene section).

[jepegit]

Release pipeline bootstrap complete:

• fix(ci): UV_NO_SOURCES on release test job #405 merged — UV_NO_SOURCES=1 at job level in release workflow (fixes editable cellpycore path in CI)
• v1.0.4a1 GitHub release existed but PyPI publish failed (test job)
• v1.0.4a2 published successfully to PyPI: https://github.com/jepegit/cellpy/releases/tag/v1.0.4a2
• origin/v2 fast-forwarded to match master (release workflow + docs + cellpycore pin)

Install: pip install cellpy==1.0.4a2 or pip install cellpy --pre

Next when ready: stable v1.0.4 tag on master after you're satisfied with the alpha.

[jepegit]

Branching scheme flipped for the v2 cycle (2026-07-16). With v1.1 released, v2
now develops directly on master; 1.x maintenance moved to the new v1.x
branch (created at v1.1.0.post1). The long-lived v2 branch is retired — do not
base new work on it (its unique commits were sync artifacts already on master).

• Updated conventions: .issueflows/04-designs-and-guides/cellpy-v2-branching.md (PR Flip branching scheme: v2 on master, 1.x maintenance on v1.x #502)
• release.yml validation now expects v1.* tags on v1.x, v2.* on master
• New v1x label for backport PRs; the v2 label is obsolete for PR targeting
• Epic child issues target master from now on

Remaining repo-settings follow-ups: protect v1.x like master; drop protection on
v2 and delete the branch.