From 288313fe93062d9ef4ca565fa70ab78e801b39a6 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 22:58:24 -0800 Subject: [PATCH 1/4] fix(golden): withdraw 0.3.0 so that data context v1 is open until 0.4.0 (ITL-1255) The 0.3.0 release revision leaves the v1 golden history and its pins move to a withdrawn record in released_manifests.json, with the date and the reason. The golden store checks the record, --release refuses a withdrawn version and keeps the record, and the tag check compares a withdrawn release's tag with its record instead of with HEAD, so it passes with or without the tag. No golden value changes. Co-Authored-By: Claude Opus 5.5 --- scripts/check_golden_tags.py | 91 ++++++++- src/orcapod/contexts/__init__.py | 2 +- src/orcapod/contexts/data/v1.json | 15 +- src/orcapod/contexts/released_manifests.json | 12 +- tests/test_check_golden_tags.py | 102 ++++++++++ tests/test_contexts/test_data_context_v1.py | 43 ++++- .../golden/generate_golden_hashes.py | 21 +- tests/test_hashing/golden/store.py | 155 ++++++++++++++- .../test_hashing/golden/test_golden_store.py | 180 ++++++++++++++++++ 9 files changed, 584 insertions(+), 37 deletions(-) diff --git a/scripts/check_golden_tags.py b/scripts/check_golden_tags.py index db007691c..618c74f3c 100644 --- a/scripts/check_golden_tags.py +++ b/scripts/check_golden_tags.py @@ -13,6 +13,13 @@ - the pins of the current data context at the tag (the manifest pin and every ``releases`` line) are present unchanged. +A withdrawn release is not compared with HEAD (ITL-1255): when HEAD's +``released_manifests.json`` records release ``X.Y.Z`` under ``withdrawn`` of the current data +context, the tag ``v`` is checked against that record instead: the record's +``revision`` and ``manifest`` must be the release digest and the manifest pin the tag +shipped. So the check passes the same way whether the tag still exists or was deleted, and +a record never excuses a release it does not describe. + The current data context is the one manifest in ``src/orcapod/contexts/data/`` at HEAD. Usage: @@ -126,8 +133,16 @@ def _current_version(repo: Path) -> str: return names[0].removesuffix(".json") -def check_tag(repo: Path, tag: str, version: str) -> list[str] | None: - """Check HEAD against one tag. +def _head_withdrawn(repo: Path, version: str) -> dict[str, Any]: + """HEAD's records of the withdrawn releases of a data context, by version.""" + pins = _show_json(repo, "HEAD", PINS) + pin = pins.get(version) if isinstance(pins, dict) else None + withdrawn = pin.get("withdrawn") if isinstance(pin, dict) else None + return withdrawn if isinstance(withdrawn, dict) else {} + + +def tag_release(repo: Path, tag: str, version: str) -> str | None: + """The release of ``version`` a tag shipped, or ``None`` when it is not one. Args: repo: Repository root. @@ -135,16 +150,68 @@ def check_tag(repo: Path, tag: str, version: str) -> list[str] | None: version: Current data context version. Returns: - ``None`` when the tag is not a release of ``version``; otherwise one sentence per - difference (empty when HEAD keeps everything the tag released). + ``X.Y.Z`` when the tag is ``v`` and its ``released_manifests.json`` pins + release ``X.Y.Z`` of ``version``; otherwise ``None``. """ release = tag.removeprefix("v") tag_pins = _show_json(repo, tag, PINS) pin = tag_pins.get(version) if isinstance(tag_pins, dict) else None if not isinstance(pin, dict) or not isinstance(pin.get("releases"), dict): return None - if release not in pin["releases"]: + return release if release in pin["releases"] else None + + +def check_withdrawn_tag(repo: Path, tag: str, version: str, release: str) -> list[str]: + """Check HEAD's record of a withdrawn release against the tag of that release. + + Args: + repo: Repository root. + tag: Tag name. + version: Current data context version. + release: The release the tag shipped, recorded as withdrawn at HEAD. + + Returns: + One sentence per difference between the record and what the tag pinned. + """ + record = _head_withdrawn(repo, version).get(release) + if not isinstance(record, dict): + return [f"{tag}: the withdrawn record of {release} is not a record"] + pin = _show_json(repo, tag, PINS)[version] + problems: list[str] = [] + if record.get("revision") != pin["releases"][release]: + problems.append( + f"{tag}: the withdrawn record of {release} does not name the release " + "revision the tag pinned" + ) + if record.get("manifest") != pin.get("manifest"): + problems.append( + f"{tag}: the withdrawn record of {release} does not name the manifest pin " + "the tag shipped" + ) + return problems + + +def check_tag(repo: Path, tag: str, version: str) -> list[str] | None: + """Check HEAD against one tag. + + A tag whose release HEAD records as withdrawn is checked by ``check_withdrawn_tag`` + instead. + + Args: + repo: Repository root. + tag: Tag name. + version: Current data context version. + + Returns: + ``None`` when the tag is not a release of ``version``; otherwise one sentence per + difference (empty when HEAD keeps everything the tag released). + """ + release = tag_release(repo, tag, version) + if release is None: return None + if release in _head_withdrawn(repo, version): + return check_withdrawn_tag(repo, tag, version, release) + pin = _show_json(repo, tag, PINS)[version] problems: list[str] = [] head_pins = _show_json(repo, "HEAD", PINS) head_pin = head_pins.get(version) if isinstance(head_pins, dict) else None @@ -230,6 +297,11 @@ def check_release(repo: Path, release: str) -> list[str]: releases = pin.get("releases") if isinstance(pin, dict) else None if not isinstance(pin, dict) or not isinstance(releases, dict): return [f"HEAD has no pin of data context {version}: {step}"] + if release in _head_withdrawn(repo, version): + return [ + f"release {release} of data context {version} was withdrawn and is never " + "released again: a package index never takes a version twice" + ] if release not in releases: return [ f"HEAD does not record release {release} of data context {version}: {step}" @@ -309,12 +381,21 @@ def main(argv: Sequence[str] | None = None) -> int: print(f"skipped: cannot check the release tags: {exc}") return 0 version = _current_version(args.repo) + withdrawn = _head_withdrawn(args.repo, version) checked: list[str] = [] problems: list[str] = [] for tag in sorted(tags): found = check_tag(args.repo, tag, version) if found is None: continue + release = tag.removeprefix("v") + if release in withdrawn and not found: + record = withdrawn[release] + print( + f"{tag}: withdrawn on {record.get('date')}, not compared with HEAD; " + "the record matches the tag" + ) + continue checked.append(tag) problems.extend(found) if problems: diff --git a/src/orcapod/contexts/__init__.py b/src/orcapod/contexts/__init__.py index f86d17dcb..af4a9b652 100644 --- a/src/orcapod/contexts/__init__.py +++ b/src/orcapod/contexts/__init__.py @@ -148,7 +148,7 @@ def get_context_info(version: str) -> dict[str, Any]: Example: >>> info = get_context_info("v1") >>> print(info['description']) - 'Data context of Orcapod v0.3: the hashing generation H1. Frozen when v0.3.0 is released, except its golden history, which only grows; editable in place while that release is prepared.' + 'Data context std:v1, the hashing generation H1, first released in Orcapod 0.4.0. Frozen when 0.4.0 is released, except its golden history, which only grows; editable in place until then.' """ registry = _get_registry() return registry.get_context_info(version) diff --git a/src/orcapod/contexts/data/v1.json b/src/orcapod/contexts/data/v1.json index c783adda3..60b06c478 100644 --- a/src/orcapod/contexts/data/v1.json +++ b/src/orcapod/contexts/data/v1.json @@ -1,8 +1,8 @@ { "context_key": "std:v1:default", "version": "v1", - "description": "Data context of Orcapod v0.3: the hashing generation H1. Frozen when v0.3.0 is released, except its golden history, which only grows; editable in place while that release is prepared.", - "released_in": "0.3.0", + "description": "Data context std:v1, the hashing generation H1, first released in Orcapod 0.4.0. Frozen when 0.4.0 is released, except its golden history, which only grows; editable in place until then.", + "released_in": null, "previous": "std:v0.1:default", "file_hasher": { "_class": "orcapod.hashing.file_hashers.FileHasher", @@ -243,21 +243,14 @@ "previous": null, "digest": "0a789cf9e8d1df9fb762d6dc2fabffcd3383cd6a21ef147e8c6583f963280c2e" }, - { - "date": "2026-11-17", - "release": "0.3.0", - "added": {}, - "previous": "0a789cf9e8d1df9fb762d6dc2fabffcd3383cd6a21ef147e8c6583f963280c2e", - "digest": "6cdd29cdc6fa98df322931e2ab0ff9df151fdb47d3381adecd9f58fd55d2fb22" - }, { "date": "2026-11-17", "release": null, "added": { "pipeline-02.json": "6d01f7186e09e8383c62f97e4063d1030a19e465248d85c401b966e62b587f0a" }, - "previous": "6cdd29cdc6fa98df322931e2ab0ff9df151fdb47d3381adecd9f58fd55d2fb22", - "digest": "19e2f1fcfd66a085a398d6bd8c80246e9f051f858877747260078cf5e3000ac6" + "previous": "0a789cf9e8d1df9fb762d6dc2fabffcd3383cd6a21ef147e8c6583f963280c2e", + "digest": "8a9857166c5b6e54ef80a7d21f345f3b15ada99037e9565dbfdb49d23947347f" } ] }, diff --git a/src/orcapod/contexts/released_manifests.json b/src/orcapod/contexts/released_manifests.json index 3c0362ab0..a59138b16 100644 --- a/src/orcapod/contexts/released_manifests.json +++ b/src/orcapod/contexts/released_manifests.json @@ -1,8 +1,14 @@ { "v1": { - "manifest": "18e7c15a446014b3e6a3178bb5daf331774f8a5214006bec40fc80442c08da09", - "releases": { - "0.3.0": "6cdd29cdc6fa98df322931e2ab0ff9df151fdb47d3381adecd9f58fd55d2fb22" + "manifest": null, + "releases": {}, + "withdrawn": { + "0.3.0": { + "date": "2026-11-17", + "reason": "Withdrawn before anyone used it: data context v1 freezes at 0.4.0 instead (ITL-1255).", + "manifest": "18e7c15a446014b3e6a3178bb5daf331774f8a5214006bec40fc80442c08da09", + "revision": "6cdd29cdc6fa98df322931e2ab0ff9df151fdb47d3381adecd9f58fd55d2fb22" + } } } } diff --git a/tests/test_check_golden_tags.py b/tests/test_check_golden_tags.py index 8e329711d..3b223553a 100644 --- a/tests/test_check_golden_tags.py +++ b/tests/test_check_golden_tags.py @@ -360,3 +360,105 @@ def test_tags_of_earlier_data_contexts_pass_with_nothing_to_check( result = _check(root, ci=True) assert result.returncode == 0, result.stderr assert "nothing to check" in result.stdout + + +# --------------------------------------------------------------------------- +# A withdrawn release (ITL-1255) +# --------------------------------------------------------------------------- + + +def _withdraw_and_change_a_released_file(repo: Path) -> None: + """Withdraw 0.3.0 at HEAD and change a file 0.3.0 listed, as v1 now may.""" + store.withdraw_release(repo, VERSION, "0.3.0", "2026-11-17", "Withdrawn.") + path = _folder(repo) / "semantic-01.json" + _ = path.write_text(path.read_text().replace("semantic_v1", "semantic_v2", 1)) + manifest = store.read_json(store.manifest_path(repo, VERSION)) + manifest["golden"]["history"] = store.with_file( + manifest["golden"]["history"], path.name, store.file_digest(path), "2026-11-18" + ) + store.write_json(store.manifest_path(repo, VERSION), manifest) + assert store.tree_problems(repo, VERSION) == [] + _commit(repo, "withdraw 0.3.0 and change a value it listed") + + +def test_a_withdrawn_release_passes_with_its_tag_and_after_it_is_deleted( + repo: Path, +) -> None: + """The order of the withdrawal and the tag deletion does not matter.""" + _withdraw_and_change_a_released_file(repo) + with_tag = _check(repo, ci=True) + assert with_tag.returncode == 0, with_tag.stderr + assert "v0.3.0: withdrawn on 2026-11-17" in with_tag.stdout + _git(repo, "tag", "-d", "v0.3.0") + without_tag = _check(repo, ci=True) + assert without_tag.returncode == 0, without_tag.stderr + assert "v0.3.0" not in without_tag.stdout + + +@pytest.mark.parametrize( + ("field", "problem"), + [ + ("revision", "does not name the release revision the tag pinned"), + ("manifest", "does not name the manifest pin the tag shipped"), + ], +) +def test_a_withdrawn_record_that_does_not_match_its_tag_fails( + repo: Path, field: str, problem: str +) -> None: + _withdraw_and_change_a_released_file(repo) + pins = store.read_json(store.pins_path(repo)) + pins[VERSION]["withdrawn"]["0.3.0"][field] = "0" * 64 + store.write_json(store.pins_path(repo), pins) + _commit(repo, "tamper with the withdrawn record") + result = _check(repo) + assert result.returncode == 1 + assert f"v0.3.0: the withdrawn record of 0.3.0 {problem}" in result.stderr + + +def test_a_release_dropped_without_a_withdrawn_record_still_fails(repo: Path) -> None: + _withdraw_and_change_a_released_file(repo) + pins = store.read_json(store.pins_path(repo)) + del pins[VERSION]["withdrawn"] + store.write_json(store.pins_path(repo), pins) + _commit(repo, "drop the release without a record") + result = _check(repo) + assert result.returncode == 1 + assert "the releases line 0.3.0" in result.stderr + assert "semantic-01.json differs from the released file" in result.stderr + + +def test_a_record_of_another_release_does_not_excuse_a_release(repo: Path) -> None: + _withdraw_and_change_a_released_file(repo) + pins = store.read_json(store.pins_path(repo)) + withdrawn = pins[VERSION]["withdrawn"] + withdrawn["0.2.9"] = withdrawn.pop("0.3.0") + store.write_json(store.pins_path(repo), pins) + _commit(repo, "record the wrong release") + result = _check(repo) + assert result.returncode == 1 + assert "the releases line 0.3.0" in result.stderr + + +def test_the_release_after_a_withdrawn_one_is_checked(repo: Path) -> None: + """The freeze at 0.4.0: its tag is compared with HEAD; the withdrawn tag is not.""" + _withdraw_and_change_a_released_file(repo) + main(["--root", str(repo), "--release", "0.4.0"]) + _commit(repo, "release 0.4.0") + _git(repo, "tag", "v0.4.0") + assert _gate(repo, "0.4.0").returncode == 0 + passing = _check(repo, ci=True) + assert passing.returncode == 0, passing.stderr + assert "HEAD keeps what v0.4.0 released" in passing.stdout + path = _folder(repo) / "semantic-01.json" + _ = path.write_text(path.read_text().replace("semantic_v2", "semantic_v3", 1)) + _commit(repo, "edit a file 0.4.0 released") + failing = _check(repo) + assert failing.returncode == 1 + assert "v0.4.0: tests/test_hashing/golden/data" in failing.stderr + + +def test_the_gate_refuses_a_withdrawn_version(repo: Path) -> None: + _withdraw_and_change_a_released_file(repo) + result = _gate(repo, "0.3.0") + assert result.returncode == 1 + assert "was withdrawn and is never released again" in result.stderr diff --git a/tests/test_contexts/test_data_context_v1.py b/tests/test_contexts/test_data_context_v1.py index 2ff80005f..baa8fc1b3 100644 --- a/tests/test_contexts/test_data_context_v1.py +++ b/tests/test_contexts/test_data_context_v1.py @@ -1,10 +1,12 @@ -"""The data context of v0.3 is ``std:v1:default``, and released manifests are frozen (ITL-944). +"""The default data context is ``std:v1:default``, and released manifests are frozen (ITL-944). A data context version names one generation of hashing. ``released_manifests.json`` pins, for each version, the sha256 of its manifest without the ``golden`` section (``null`` while the manifest is open) and, under ``releases``, the digest of each library release's -revision in the manifest's golden history (ITL-946). The rules of the golden history and -its folder are stated in ``tests/test_hashing/golden/store.py``. +revision in the manifest's golden history (ITL-946). A withdrawn release is recorded under +``withdrawn`` and freezes nothing: 0.3.0 was withdrawn on 2026-11-17, so v1 is open until +0.4.0 (ITL-1255). The rules of the golden history and its folder are stated in +``tests/test_hashing/golden/store.py``. """ from __future__ import annotations @@ -29,7 +31,9 @@ def _pins() -> dict[str, dict[str, Any]]: - """The pin of each manifest, by version: ``{"manifest": ..., "releases": {...}}``.""" + """The pin of each manifest, by version: ``{"manifest": ..., "releases": {...}}``, + with ``"withdrawn": {...}`` when a release was withdrawn. + """ return json.loads((CONTEXTS_DIR / "released_manifests.json").read_text()) @@ -122,6 +126,37 @@ def test_the_pins_agree_with_the_golden_history(version: str) -> None: assert problems == [] +# --------------------------------------------------------------------------- +# 0.3.0 is withdrawn: v1 is open until 0.4.0 (developer, November 17, 2026; ITL-1255) +# --------------------------------------------------------------------------- + + +def test_0_3_0_is_recorded_as_withdrawn_with_the_pins_it_shipped() -> None: + """The record keeps the date, the reason and the exact pins 0.3.0 shipped.""" + withdrawn = _pins()["v1"]["withdrawn"] + assert list(withdrawn) == ["0.3.0"] + record = withdrawn["0.3.0"] + assert record["date"] == "2026-11-17" + assert "0.4.0" in record["reason"] + assert record["manifest"] == ( + "18e7c15a446014b3e6a3178bb5daf331774f8a5214006bec40fc80442c08da09" + ) + assert record["revision"] == ( + "6cdd29cdc6fa98df322931e2ab0ff9df151fdb47d3381adecd9f58fd55d2fb22" + ) + + +def test_v1_is_open_until_0_4_0() -> None: + """No release of v1 stands: no manifest pin, no releases line, no release revision.""" + pin = _pins()["v1"] + assert pin["manifest"] is None + assert pin["releases"] == {} + assert _manifest("v1")["released_in"] is None + history = _history("v1") + assert [revision["release"] for revision in history] == [None] * len(history) + assert store.released_files(history) == set() + + # --------------------------------------------------------------------------- # The contents of the manifest (ITL-938 design document, section 7.4) # --------------------------------------------------------------------------- diff --git a/tests/test_hashing/golden/generate_golden_hashes.py b/tests/test_hashing/golden/generate_golden_hashes.py index 7d233e58c..1b7e8d6d3 100644 --- a/tests/test_hashing/golden/generate_golden_hashes.py +++ b/tests/test_hashing/golden/generate_golden_hashes.py @@ -4,7 +4,7 @@ uv run python tests/test_hashing/golden/generate_golden_hashes.py # add uv run python tests/test_hashing/golden/generate_golden_hashes.py --check # report - uv run python tests/test_hashing/golden/generate_golden_hashes.py --release 0.3.0 + uv run python tests/test_hashing/golden/generate_golden_hashes.py --release 0.4.0 uv run python tests/test_hashing/golden/generate_golden_hashes.py --remove The golden values of the current data context live in @@ -20,8 +20,15 @@ by an earlier release is no longer found, is keyed differently, or is read under another column name. **A changed value is a breaking change.** -The rules (developer, November 15, 2026, ITL-946): +The rules (developer, November 15, 2026, ITL-946; reopened November 17, 2026, ITL-1255): +0. Data context v1 is open until the 0.4.0 release. 0.3.0 was withdrawn (2026-11-17) before + anyone used it: its release revision is out of the history and its pins are kept under + ``withdrawn`` in ``released_manifests.json``, so no file is released today. Until 0.4.0, + a change to any v1 value needs the developer's approval of the exact list of entries + that move, each explained; it is made with ``--remove`` then ``--add`` (rule 4). 0.4.0 + freezes v1 with ``--release 0.4.0``; so would any version published before it, a + pre-release included (the Release workflow requires the release step for every version). 1. A golden file listed by a released revision never changes and is never removed. This script never rewrites one. 2. Adding values is allowed in any release. ``--add`` (the default) writes the entries the @@ -56,8 +63,8 @@ ``--release X.Y.Z`` is the golden step of a release pull request: it appends the release revision (``added`` empty), pins its digest under ``releases`` in ``src/orcapod/contexts/released_manifests.json``, and, at the data context's first release, -sets ``released_in`` and pins the digest of the manifest without ``golden``. It computes no -hash. Try it on a copy first with ``--root`` (``store.copy_tree`` makes one). +sets ``released_in`` and pins the digest of the manifest without ``golden``. It keeps the +``withdrawn`` records and refuses a withdrawn version. It computes no hash. Try it on a copy first with ``--root`` (``store.copy_tree`` makes one). Comparing releases ------------------ @@ -295,6 +302,11 @@ def release(root: pathlib.Path, version: str, release_text: str) -> str: pin = pins[version] if name in pin["releases"]: raise SystemExit(f"{name} is already released") + if name in store.withdrawn_releases(pin): + raise SystemExit( + f"{name} was withdrawn and is never released again: a package index never " + "takes a version twice; release the next version" + ) history = manifest["golden"]["history"] if not history: raise SystemExit("the golden history lists no file") @@ -304,6 +316,7 @@ def release(root: pathlib.Path, version: str, release_text: str) -> str: manifest["released_in"] = name fixed = store.fixed_manifest_digest(manifest) pins[version] = { + **pin, "manifest": fixed, "releases": {**pin["releases"], name: history[-1]["digest"]}, } diff --git a/tests/test_hashing/golden/store.py b/tests/test_hashing/golden/store.py index c75921c81..0904e748a 100644 --- a/tests/test_hashing/golden/store.py +++ b/tests/test_hashing/golden/store.py @@ -18,6 +18,19 @@ in ``src/orcapod/contexts/released_manifests.json``. Revisions after the last release revision may still be edited (their digests are recomputed); the ones up to it may not. +A withdrawn release (0.3.0, withdrawn on 2026-11-17 before anyone used it; ITL-1255) freezes +nothing. Its release revision is taken out of the history, and the pins it shipped are kept +under ``withdrawn`` in ``released_manifests.json``, beside the pins of the releases that +stand, with the date and the reason:: + + {"": {"manifest": , "releases": {...}, + "withdrawn": {"X.Y.Z": {"date": "YYYY-MM-DD", "reason": "...", + "manifest": , + "revision": }}}} + +``scripts/check_golden_tags.py`` compares the record with the tag of that release, when the +tag still exists, instead of comparing HEAD with it. + This module holds the rules: reading the folder, computing digests, and listing what in a tree breaks the rules. ``generate_golden_hashes.py`` writes the files and the history, ``test_golden_hashes.py`` and ``tests/test_contexts/test_data_context_v1.py`` check them, @@ -55,7 +68,11 @@ REVISION_FIELDS = ("date", "release", "added", "previous") """The fields of a revision its digest covers, besides the digest itself.""" +WITHDRAWN_FIELDS = ("date", "reason", "manifest", "revision") +"""The fields of the record of a withdrawn release, under ``withdrawn`` in a pin.""" + _DATE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$") +_SHA256 = re.compile(r"^[0-9a-f]{64}$") class GoldenLayoutError(ValueError): @@ -158,7 +175,7 @@ def reopen_tree(root: Path, version: str, date: str) -> None: The history becomes one open revision listing every file of the golden folder with its sha256; ``released_in`` is cleared and the pin becomes ``{"manifest": null, - "releases": {}}``. The golden files are not touched. Tests that add or release on a + "releases": {}}``, without any ``withdrawn`` record. The golden files are not touched. Tests that add or release on a copy start from this state, so they keep working after the repository's own releases. Args: @@ -184,6 +201,58 @@ def reopen_tree(root: Path, version: str, date: str) -> None: write_json(pins_path(root), pins) +def withdraw_release( + root: Path, version: str, release: str, date: str, reason: str +) -> None: + """Withdraw the last release of a data context in a tree: the edit ITL-1255 made for 0.3.0. + + The release revision is taken out of the golden history and the open revisions after it + are rechained; the release's pins move to a ``withdrawn`` record with the date and the + reason. The releases before it, their revisions and the manifest pin stay as they are; + when no release is left, ``released_in`` is cleared and the manifest pin becomes + ``null``, so the data context is open again. The golden files are not touched. + + Args: + root: Project root. + version: Data context version. + release: The release to withdraw, normalized (``0.3.0``). + date: The date of the withdrawal, ``YYYY-MM-DD``. + reason: Why the release was withdrawn. + + Raises: + ValueError: ``release`` is not the last release of the tree's history and pins. + """ + path = manifest_path(root, version) + manifest = read_json(path) + pins = read_json(pins_path(root)) + pin = pins[version] + history = manifest["golden"]["history"] + index = last_release_index(history) + if ( + index is None + or history[index]["release"] != release + or release not in pin["releases"] + ): + raise ValueError(f"{release} is not the last release of data context {version}") + record = { + "date": date, + "reason": reason, + "manifest": pin["manifest"], + "revision": pin["releases"][release], + } + manifest["golden"]["history"] = rechain([*history[:index], *history[index + 1 :]]) + releases = {name: d for name, d in pin["releases"].items() if name != release} + if not releases: + manifest["released_in"] = None + pins[version] = { + "manifest": pin["manifest"] if releases else None, + "releases": releases, + "withdrawn": {**withdrawn_releases(pin), release: record}, + } + write_json(path, manifest) + write_json(pins_path(root), pins) + + # --------------------------------------------------------------------------- # Digests # --------------------------------------------------------------------------- @@ -527,16 +596,72 @@ def folder_problems(history: Sequence[Mapping[str, Any]], folder: Path) -> list[ return problems +def withdrawn_releases(pin: Mapping[str, Any]) -> dict[str, Any]: + """The records of a pin's withdrawn releases, by version; empty when it has none.""" + withdrawn = pin.get("withdrawn", {}) + return withdrawn if isinstance(withdrawn, dict) else {} + + +def withdrawn_problems(pin: Mapping[str, Any]) -> list[str]: + """What breaks the shape of a pin's ``withdrawn`` records. + + ``withdrawn`` is optional. When present it maps normalized release versions to records + with exactly the fields ``date`` (``YYYY-MM-DD``), ``reason`` (non-empty text), + ``manifest`` (the manifest pin the release shipped: a sha256 hex digest, or ``null``) + and ``revision`` (the digest of its release revision). + + Args: + pin: The version's value in ``released_manifests.json``. + + Returns: + One sentence per problem. + """ + if "withdrawn" not in pin: + return [] + withdrawn = pin["withdrawn"] + if not isinstance(withdrawn, dict): + return ["withdrawn is not a mapping of release versions to records"] + problems: list[str] = [] + for release, record in withdrawn.items(): + label = f"withdrawn release {release}" + try: + normalized = normalize_release(release) + except ValueError: + normalized = None + if normalized != release: + problems.append(f"{label} is not a normalized release version") + if not isinstance(record, dict) or set(record) != set(WITHDRAWN_FIELDS): + problems.append( + f"{label} does not have exactly the fields {sorted(WITHDRAWN_FIELDS)}" + ) + continue + if not isinstance(record["date"], str) or not _DATE.match(record["date"]): + problems.append(f"{label} has no YYYY-MM-DD date") + if not isinstance(record["reason"], str) or not record["reason"].strip(): + problems.append(f"{label} gives no reason") + if record["manifest"] is not None and not ( + isinstance(record["manifest"], str) and _SHA256.match(record["manifest"]) + ): + problems.append(f"{label}: manifest is neither null nor a sha256 digest") + if not isinstance(record["revision"], str) or not _SHA256.match( + record["revision"] + ): + problems.append(f"{label}: revision is not a sha256 digest") + return problems + + def pin_problems( manifest: Mapping[str, Any], pin: Any, history: Sequence[Mapping[str, Any]] ) -> list[str]: """What breaks the agreement between a manifest, its history and its pin. - The pin is ``{"manifest": , "releases": {: }}``. The - pinned releases are exactly the release revisions, each with its digest; the manifest - pin is set exactly when ``released_in`` is, and then equals the digest of the manifest - without ``golden``; ``released_in`` is the first release; and a manifest with releases - is pinned. + The pin is ``{"manifest": , "releases": {: }}``, + optionally with ``withdrawn`` records (``withdrawn_problems``). The pinned releases are + exactly the release revisions, each with its digest; the manifest pin is set exactly + when ``released_in`` is, and then equals the digest of the manifest without ``golden``; + ``released_in`` is the first release; and a manifest with releases is pinned. A + withdrawn release is neither pinned under ``releases`` nor a release revision, so it + freezes nothing. Args: manifest: Parsed manifest. @@ -548,12 +673,24 @@ def pin_problems( """ if ( not isinstance(pin, dict) - or set(pin) != {"manifest", "releases"} + or not {"manifest", "releases"} + <= set(pin) + <= {"manifest", "releases", "withdrawn"} or not isinstance(pin["releases"], dict) ): - return ['the pin is not {"manifest": ..., "releases": {...}}'] - problems: list[str] = [] + return [ + 'the pin is not {"manifest": ..., "releases": {...}}, optionally with ' + '"withdrawn": {...}' + ] + problems = withdrawn_problems(pin) revisions = {r["release"]: r["digest"] for r in history if r["release"]} + for release in withdrawn_releases(pin): + if release in pin["releases"]: + problems.append(f"withdrawn release {release} is pinned under releases") + if release in revisions: + problems.append( + f"withdrawn release {release} is a release revision of the history" + ) for release, digest in pin["releases"].items(): if release not in revisions: problems.append(f"pinned release {release} is not a release revision") diff --git a/tests/test_hashing/golden/test_golden_store.py b/tests/test_hashing/golden/test_golden_store.py index c38bda799..a3e3292ac 100644 --- a/tests/test_hashing/golden/test_golden_store.py +++ b/tests/test_hashing/golden/test_golden_store.py @@ -558,3 +558,183 @@ def test_release_refuses_a_version_it_cannot_record(tree: Path, version: str) -> def test_allow_errors_is_only_for_stdout(tree: Path) -> None: with pytest.raises(SystemExit): main(["--root", str(tree), "--allow-errors", "--group", "schema"]) + + +# --------------------------------------------------------------------------- +# A withdrawn release (ITL-1255) +# --------------------------------------------------------------------------- + +REASON = "Withdrawn before anyone used it." + + +def _released_and_withdrawn(tree: Path) -> Path: + """Release 0.3.0 on the copy, add a file after it, then withdraw 0.3.0.""" + main(["--root", str(tree), "--release", "0.3.0"]) + _record(tree, NEXT_SCHEMA, {"later.entry": "x"}) + store.withdraw_release(tree, VERSION, "0.3.0", "2026-11-17", REASON) + return tree + + +def test_a_withdrawn_release_freezes_nothing(tree: Path) -> None: + """After the withdrawal the tree is sound and open, and the record keeps the pins.""" + main(["--root", str(tree), "--release", "0.3.0"]) + released = _pin(tree) + files = _snapshot(_folder(tree)) + store.withdraw_release(tree, VERSION, "0.3.0", "2026-11-17", REASON) + manifest = _manifest(tree) + assert store.tree_problems(tree, VERSION) == [] + assert manifest["released_in"] is None + assert store.released_files(manifest["golden"]["history"]) == set() + assert [r["release"] for r in manifest["golden"]["history"]] == [None] + assert _pin(tree) == { + "manifest": None, + "releases": {}, + "withdrawn": { + "0.3.0": { + "date": "2026-11-17", + "reason": REASON, + "manifest": released["manifest"], + "revision": released["releases"]["0.3.0"], + } + }, + } + assert _snapshot(_folder(tree)) == files + + +def test_withdrawing_rechains_the_revisions_after_the_release(tree: Path) -> None: + _ = _released_and_withdrawn(tree) + history = _history(tree) + assert [r["release"] for r in history] == [None, None] + assert NEXT_SCHEMA in history[1]["added"] + assert history[1]["previous"] == history[0]["digest"] + assert store.history_problems(history) == [] + + +def test_withdrawing_only_takes_the_last_release(tree: Path) -> None: + main(["--root", str(tree), "--release", "0.3.0"]) + _record(tree, NEXT_SCHEMA, {"later.entry": "x"}) + main(["--root", str(tree), "--release", "0.3.1"]) + with pytest.raises(ValueError, match="not the last release"): + store.withdraw_release(tree, VERSION, "0.3.0", "2026-11-17", REASON) + store.withdraw_release(tree, VERSION, "0.3.1", "2026-11-17", REASON) + pin = _pin(tree) + assert set(pin["releases"]) == {"0.3.0"} + assert pin["manifest"] is not None + assert _manifest(tree)["released_in"] == "0.3.0" + assert store.tree_problems(tree, VERSION) == [] + + +def test_a_value_a_withdrawn_release_listed_can_change(tree: Path) -> None: + """The approved-change procedure works on a file the withdrawn release listed.""" + main(["--root", str(tree), "--release", "0.3.0"]) + name = NEWEST_SCHEMA + entries = list(store.read_json(_folder(tree) / name)) + with pytest.raises(SystemExit, match="released"): + main(["--root", str(tree), "--remove", entries[0]]) + store.withdraw_release(tree, VERSION, "0.3.0", "2026-11-17", REASON) + main(["--root", str(tree), "--remove", entries[-1], "--remove", entries[0]]) + remaining = store.read_json(_folder(tree) / name) + assert entries[0] not in remaining and entries[-1] not in remaining + assert store.tree_problems(tree, VERSION) == [] + main(["--root", str(tree), "--group", "schema"]) + assert list(store.read_json(_folder(tree) / name)) == sorted(entries) + assert store.tree_problems(tree, VERSION) == [] + + +def test_release_refuses_a_withdrawn_version_and_writes_nothing(tree: Path) -> None: + _ = _released_and_withdrawn(tree) + before = ( + _snapshot(tree / store.CONTEXTS_DIR), + _snapshot(tree / store.CONTEXTS_DIR / "data"), + ) + for version in ("0.3.0", "v0.3.0"): + with pytest.raises(SystemExit, match="withdrawn"): + main(["--root", str(tree), "--release", version]) + after = ( + _snapshot(tree / store.CONTEXTS_DIR), + _snapshot(tree / store.CONTEXTS_DIR / "data"), + ) + assert after == before + + +def test_the_next_release_freezes_again_and_keeps_the_record(tree: Path) -> None: + """The freeze at 0.4.0: the release step after a withdrawal.""" + _ = _released_and_withdrawn(tree) + withdrawn = _pin(tree)["withdrawn"] + main(["--root", str(tree), "--release", "0.4.0"]) + manifest = _manifest(tree) + history = manifest["golden"]["history"] + assert manifest["released_in"] == "0.4.0" + assert [r["release"] for r in history] == [None, None, "0.4.0"] + assert _pin(tree) == { + "manifest": store.fixed_manifest_digest(manifest), + "releases": {"0.4.0": history[-1]["digest"]}, + "withdrawn": withdrawn, + } + assert store.released_files(history) == set(_snapshot(_folder(tree))) + assert store.tree_problems(tree, VERSION) == [] + assert store.final_release_problems(_pin(tree), "0.4.0") == [] + + +def _set_record(field: str, value: Any) -> Any: + def change(pin: dict[str, Any], history: list[dict[str, Any]]) -> None: + pin["withdrawn"]["0.3.0"][field] = value + + return change + + +def _drop_record_field(pin: dict[str, Any], history: list[dict[str, Any]]) -> None: + del pin["withdrawn"]["0.3.0"]["reason"] + + +def _rename_record(pin: dict[str, Any], history: list[dict[str, Any]]) -> None: + pin["withdrawn"]["v0.3.0"] = pin["withdrawn"].pop("0.3.0") + + +def _pin_withdrawn_as_release( + pin: dict[str, Any], history: list[dict[str, Any]] +) -> None: + pin["releases"]["0.3.0"] = pin["withdrawn"]["0.3.0"]["revision"] + + +@pytest.mark.parametrize( + ("change", "problem"), + [ + (_set_record("date", "17 November 2026"), "no YYYY-MM-DD date"), + (_set_record("reason", " "), "gives no reason"), + (_set_record("manifest", "not a digest"), "manifest is neither null"), + (_set_record("revision", None), "revision is not a sha256 digest"), + (_drop_record_field, "does not have exactly the fields"), + (_rename_record, "not a normalized release version"), + (lambda pin, h: pin.update(withdrawn=["0.3.0"]), "withdrawn is not a mapping"), + (_pin_withdrawn_as_release, "withdrawn release 0.3.0 is pinned under releases"), + (lambda pin, h: pin.update(extra={}), "the pin is not"), + ], +) +def test_a_withdrawn_record_that_breaks_the_rules_is_reported( + tree: Path, change: Any, problem: str +) -> None: + _ = _released_and_withdrawn(tree) + pins = store.read_json(store.pins_path(tree)) + change(pins[VERSION], _history(tree)) + store.write_json(store.pins_path(tree), pins) + problems = store.tree_problems(tree, VERSION) + assert any(problem in p for p in problems), problems + + +def test_a_withdrawn_release_left_in_the_history_is_reported(tree: Path) -> None: + """A record does not withdraw a release whose revision is still in the history.""" + main(["--root", str(tree), "--release", "0.3.0"]) + pins = store.read_json(store.pins_path(tree)) + pin = pins[VERSION] + pin["withdrawn"] = { + "0.3.0": { + "date": "2026-11-17", + "reason": REASON, + "manifest": pin["manifest"], + "revision": pin["releases"].pop("0.3.0"), + } + } + store.write_json(store.pins_path(tree), pins) + problems = store.tree_problems(tree, VERSION) + assert any("is a release revision of the history" in p for p in problems), problems From c4034d497b592a3cf8ee7b7e85dfe8d894c7f8eb Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 23:01:29 -0800 Subject: [PATCH 2/4] docs: v1 is open until 0.4.0 and 0.3.0 is withdrawn (ITL-1255) The golden rules (CLAUDE.md, .zed/rules, the golden README and reference page, RELEASING.md) state that v1 is open until 0.4.0, how a release is withdrawn, and that publishing any version, a pre-release included, freezes v1. The install pages say to install from the repository until 0.4.0. The CHANGELOG.md heading of 0.3.0 is marked withdrawn, on the developer's word. Co-Authored-By: Claude Opus 5.5 --- .zed/rules | 18 +++++-- CHANGELOG.md | 5 +- CLAUDE.md | 18 +++++-- README.md | 25 +++++++--- RELEASING.md | 40 ++++++++++++--- changelog.d/ITL-1255.md | 14 ++++++ docs/getting-started.md | 4 ++ docs/index.md | 11 ++++- docs/reference/golden-hashes.md | 77 +++++++++++++++++++++++------ docs/troubleshooting.md | 4 +- docs/tutorial/00-setup.md | 4 +- tests/test_hashing/golden/README.md | 8 ++- 12 files changed, 185 insertions(+), 43 deletions(-) create mode 100644 changelog.d/ITL-1255.md diff --git a/.zed/rules b/.zed/rules index 915a08c69..8723b7d0e 100644 --- a/.zed/rules +++ b/.zed/rules @@ -487,6 +487,15 @@ Orcapod stores or embeds in a name is pinned in the golden folder of the current - A failing golden entry means a hash moved. Treat it as a bug in the change, not a stale file. Never edit or regenerate a golden file to make a test pass. +- Data context v1 is open until the 0.4.0 release (developer, November 17, 2026, ITL-1255). + 0.3.0 was withdrawn on 2026-11-17, before anyone used it: its release revision is out of the + golden history, and the pins it shipped are kept under `withdrawn` in + `released_manifests.json`, with the date and the reason, so no v1 file is released today. + Until 0.4.0, a change to any v1 golden value needs the developer's approval of the exact + list of entries that move, each explained; it is made with `--remove `, then the + generator writes the new value. `--release 0.4.0` freezes v1. Any version published + before it, a pre-release included, would freeze v1 there: the Release workflow requires + the release step for every version. A withdrawn version is never released again. - The unit of immutability is the golden file. The manifest's `golden.history` (`src/orcapod/contexts/data/.json`) lists every file with the sha256 of its bytes; a release appends a revision with `added: {}`, pinned in @@ -506,8 +515,10 @@ Orcapod stores or embeds in a name is pinned in the golden folder of the current a migration assessment: `generate_golden_hashes.py --remove ` (refuses an entry a release lists), then the generator writes the new value. - The release pull request runs `generate_golden_hashes.py --release X.Y.Z`. CI checks HEAD - against every release tag (`scripts/check_golden_tags.py`). Never mark a golden entry - `skip` or `xfail`; the only skip is the optional-package rule (`torch`). + against every release tag (`scripts/check_golden_tags.py`); the tag of a withdrawn release + is checked against its `withdrawn` record instead, so the check passes whether or not that + tag still exists. Never mark a golden entry `skip` or `xfail`; the only skip is the + optional-package rule (`torch`). - Never move or rename the fixtures in `tests/test_hashing/golden/cases.py`: function pods, dataclasses and pydantic models hash with their module path. @@ -856,7 +867,8 @@ generation of hashing; rows of the current data context are the current entries. (manifest), with one releases line per library release (ITL-946). Only its golden history grows, by appending. A change that moves a released golden hash value, for any reason (a logical type's own change included), needs a new data context version with its - own manifest file, never an edit of a released one. + own manifest file, never an edit of a released one. A withdrawn release freezes nothing: + its pins move to a withdrawn record (0.3.0, ITL-1255: v1 is open until 0.4.0). - In memory the data context column is still _context_key (ColumnConfig context). - A writer refuses an input of another data context than its own (contexts/stored.require_same_data_context, InputValidationError naming both keys) before diff --git a/CHANGELOG.md b/CHANGELOG.md index 1168ac5cf..a52e373ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Changelog -## [0.3.0] — 2026-11-17 +## [0.3.0] — 2026-11-17 (withdrawn) + +Withdrawn on 2026-11-17, before anyone used it: removed from PyPI, its tag and GitHub Release +deleted. Its changes ship in 0.4.0; data context v1 freezes there. ### Breaking changes and migration diff --git a/CLAUDE.md b/CLAUDE.md index a06981d07..01e8a0f69 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -498,6 +498,15 @@ Orcapod stores or embeds in a name is pinned in the golden folder of the current - A failing golden entry means a hash moved. Treat it as a bug in the change, not a stale file. Never edit or regenerate a golden file to make a test pass. +- Data context v1 is open until the 0.4.0 release (developer, November 17, 2026, ITL-1255). + 0.3.0 was withdrawn on 2026-11-17, before anyone used it: its release revision is out of the + golden history, and the pins it shipped are kept under `withdrawn` in + `released_manifests.json`, with the date and the reason, so no v1 file is released today. + Until 0.4.0, a change to any v1 golden value needs the developer's approval of the exact + list of entries that move, each explained; it is made with `--remove `, then the + generator writes the new value. `--release 0.4.0` freezes v1. Any version published + before it, a pre-release included, would freeze v1 there: the Release workflow requires + the release step for every version. A withdrawn version is never released again. - The unit of immutability is the golden file. The manifest's `golden.history` (`src/orcapod/contexts/data/.json`) lists every file with the sha256 of its bytes; a release appends a revision with `added: {}`, pinned in @@ -517,8 +526,10 @@ Orcapod stores or embeds in a name is pinned in the golden folder of the current a migration assessment: `generate_golden_hashes.py --remove ` (refuses an entry a release lists), then the generator writes the new value. - The release pull request runs `generate_golden_hashes.py --release X.Y.Z`. CI checks HEAD - against every release tag (`scripts/check_golden_tags.py`). Never mark a golden entry - `skip` or `xfail`; the only skip is the optional-package rule (`torch`). + against every release tag (`scripts/check_golden_tags.py`); the tag of a withdrawn release + is checked against its `withdrawn` record instead, so the check passes whether or not that + tag still exists. Never mark a golden entry `skip` or `xfail`; the only skip is the + optional-package rule (`torch`). - Never move or rename the fixtures in `tests/test_hashing/golden/cases.py`: function pods, dataclasses and pydantic models hash with their module path. @@ -884,7 +895,8 @@ current data context are the current entries. (`manifest`), with one `releases` line per library release (ITL-946). Only its `golden` history grows, by appending. A change that moves a released golden hash value, for any reason (a logical type's own change included), needs a new data context version with its - own manifest file, never an edit of a released one. + own manifest file, never an edit of a released one. A withdrawn release freezes nothing: + its pins move to a `withdrawn` record (0.3.0, ITL-1255: v1 is open until 0.4.0). - In memory the data context column is still `_context_key` (`ColumnConfig(context=True)`). - A writer refuses an input of another data context than its own (`contexts/stored.require_same_data_context`, `InputValidationError` naming both keys) diff --git a/README.md b/README.md index d103575c7..408a38154 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,15 @@ In an environment not managed by uv, use `pip install orcapod` instead. A plain `uv add orcapod` installs the latest stable release; to try a release candidate, name it, for example `uv add "orcapod==0.4.0rc1"`. -0.3.0 is the first release on PyPI since 0.1.4; 0.2.0 was never published to PyPI. Tables -written by 0.2.0 or earlier are not read by 0.3.0: see +No release after 0.1.4 is available on PyPI yet: 0.2.0 was never published, and 0.3.0 was +withdrawn on 2026-11-17. The next release is 0.4.0; `uv add orcapod` installs it once it is +out. Until then, install the development version from the repository: + +```bash +uv add git+https://github.com/metamorphic-labs/orcapod-python +``` + +Tables written by 0.2.0 or earlier are not read by this version: see [Upgrading from 0.2.0](https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md#upgrading-from-020) (it also covers 0.1.4). @@ -112,11 +119,12 @@ session. ## Status -Orcapod is before version 1.0. In 0.3.0: +Orcapod is before version 1.0. In the development version (0.4.0 is next): -- **Hash values are frozen for data context v1.** Hashes name stored tables and find stored - results again, so a hash value released in 0.3.0 does not change in a later release of the - same data context; CI checks this. See +- **Hash values of data context v1 freeze at 0.4.0.** Hashes name stored tables and find + stored results again, so a hash value released in 0.4.0 will not change in a later release + of the same data context; CI checks this. Until 0.4.0 a v1 hash may still change, only by + an approved and explained change (0.3.0, which first shipped v1, was withdrawn). See [Golden hashes](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/reference/golden-hashes.md). - **Library value types are provisional.** The hashes of `numpy.ndarray`, `torch.Tensor`, and pandas and polars `DataFrame` and `Series` values are provisional until the library value @@ -124,8 +132,9 @@ Orcapod is before version 1.0. In 0.3.0: computed again. Using one issues `ProvisionalHashWarning` once per type per process. - **Stores from earlier versions are not read as current.** Tables written by 0.1.x or 0.2.0 - are neither read as results nor modified, and results stored by a development build of 0.3 - are not found again: 0.3.0 computes them again. Read + are neither read as results nor modified, and results stored by a development build before + v1 was released may not be found again by a later build, which then computes them again. + Read [Upgrading from 0.2.0](https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md#upgrading-from-020) before running a job over an old store, in particular one with side-effect nodes. - **Connector databases cannot hold function nodes yet.** A job over a SQLite, PostgreSQL or diff --git a/RELEASING.md b/RELEASING.md index d40c0d97a..1ab072e86 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -26,7 +26,8 @@ setting, secret or environment. `nauticalab/orcapod-python`: `main` was pushed there by fast-forward at a release point, the Release workflow ran there, and the tag was fetched back into `metamorphic-labs` (ITL-1007). Every release tag up to `v0.3.0` is also here, on the same commit; `v0.2.0` (a -tag only, never published) exists only here and stays as it is. +tag only, never published) exists only here and stays as it is. `0.3.0` was withdrawn on +2026-11-17 (see *Withdrawn releases*); the next release is `0.4.0`. ## Branching Model @@ -120,13 +121,38 @@ against are in `docs/reference/golden-hashes.md`. (before 1.0) or a major one, never in a patch. - When a new data context starts, the old context's golden files and code move to `orcapod-sanctuary`; this repository carries only the current context's golden folder. +- Data context v1 is open until `0.4.0` (developer, November 17, 2026, ITL-1255): `0.3.0` is + withdrawn, so no v1 golden file is released. Until `0.4.0`, a change to a v1 value needs the + developer's approval of the exact list of entries that move, each explained. The release + step of `0.4.0` freezes v1. Every published version needs the release step, a pre-release + included (the gate below refuses to tag one without it), so **publishing `0.4.0rc1` would + freeze v1 at the release candidate**: plan the release around it. - Release tags are protected on `metamorphic-labs/orcapod-python` (and on `nauticalab/orcapod-python`, the release repository up to `0.3.0`): the repository ruleset `protect-release-tags` (target `refs/tags/v*`; rules deletion, update and non-fast-forward; no bypass actors) is in place since 2026-11-15. A `v*` tag can be created, as the Release workflow does, but never moved or deleted. This is a precondition of the CI tag check (`scripts/check_golden_tags.py`), which compares HEAD with every release tag of the current data context. Agents never change - repository settings. + repository settings. The one exception is the tag `v0.3.0` of the withdrawn release, which + the developer deletes (see *Withdrawn releases*). + +### Withdrawn releases + +`0.3.0` (2026-11-17) was withdrawn by the developer on 2026-11-17, before anyone used it, so +that data context v1 is frozen at `0.4.0` instead, after every open question that can move a +golden value is settled (ITL-1255). The developer's acts, never an agent's: withdrawing the +version from PyPI (yanked or deleted), lifting `protect-release-tags` to delete the tag +`v0.3.0` (here and on `nauticalab`), and deleting its GitHub Release. In the repository the +release revision left the v1 golden history and its pins moved to the `withdrawn` record in +`src/orcapod/contexts/released_manifests.json`, with the date and the reason +(`docs/reference/golden-hashes.md`, *Withdrawing a release*). The tag check compares the tag, +while it exists, with that record, so CI passes before and after the tag is deleted. + +- The version `0.3.0` is never used again: PyPI never takes a version twice, and + `generate_golden_hashes.py --release` and the release gate refuse a withdrawn version. +- The version of a build comes from the git tags (`hatch-vcs`). After `v0.3.0` is deleted, a + build from `main` reports a `0.2.x` development version until the next tag exists, so a + project that requires `orcapod>=0.3.1.dev0` no longer resolves to a build of `main`. ## Cutting a Release @@ -219,10 +245,9 @@ secrets or environments: 5. The `LINEAR_ACCESS_KEY` repository secret, for the Linear jobs (see *Linear Release System*). Codecov needs no secret (see *Coverage uploads*). 6. Before the first release cut here: the latest GitHub Release in this repository is - `v0.1.2` (the GitHub Release of `v0.3.0` is on `nauticalab`), and the generated - release notes start at the latest earlier Release. Create a GitHub Release for `v0.3.0` - here (its notes copied from `nauticalab`) so that the next notes start at `v0.3.0`, or edit - the next Release's notes after the run. + `v0.1.2` (`0.3.0` is withdrawn and has none), and the generated release notes start at the + latest earlier Release. Edit the notes of `0.4.0` after the run, or create a GitHub Release + for `v0.2.0` here first so that the next notes start there. ### Coverage uploads @@ -333,7 +358,8 @@ failure in a later job leaves the tag behind. | `linear-sync` | Unknown: it needs only `build` and runs in parallel with publishing, so it can fail before anything is published | Check `publish-testpypi` and `publish-pypi` first and recover them by their rows above. Then re-run `linear-sync`; it does not affect publishing | | `linear-complete` | Release is published (it runs only after `publish-pypi` and `linear-sync` succeed) | Re-run the failed job; it does not affect publishing | -Never delete a tag whose version has been published to any package index. +Never delete a tag whose version has been published to any package index. The one +exception is `v0.3.0`, whose release the developer withdrew (see *Withdrawn releases*). ## Release Lineage diff --git a/changelog.d/ITL-1255.md b/changelog.d/ITL-1255.md new file mode 100644 index 000000000..46002ee0d --- /dev/null +++ b/changelog.d/ITL-1255.md @@ -0,0 +1,14 @@ +### Changed + +- **0.3.0 is withdrawn, and data context v1 is open until 0.4.0.** 0.3.0 was withdrawn on + 2026-11-17, before anyone used it, so that v1 of every hash freezes at 0.4.0 instead. The + repository records the withdrawal: the 0.3.0 release revision left the v1 golden history, + and the pins it shipped are kept under `withdrawn` in + `src/orcapod/contexts/released_manifests.json`, with the date and the reason. A withdrawn + version is never released again. No hash value changed. Until 0.4.0, a change to a v1 hash + value is made only with the developer's approval of the exact list of entries that move, + each explained; see *Withdrawing a release* in `docs/reference/golden-hashes.md`. + (ITL-1255) +- **Install from the repository until 0.4.0.** No release after 0.1.4 is on PyPI, so a plain + `uv add orcapod` installs 0.1.4; install the development version with + `uv add git+https://github.com/metamorphic-labs/orcapod-python`. (ITL-1255) diff --git a/docs/getting-started.md b/docs/getting-started.md index 45959959d..ee455df46 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -17,6 +17,10 @@ uv run python my_pipeline.py In an environment not managed by uv, `pip install orcapod` installs it instead. +Until 0.4.0 is released, PyPI has no current version (0.3.0 was withdrawn, and a plain +`uv add orcapod` would install 0.1.4): add the development version instead, +`uv add git+https://github.com/metamorphic-labs/orcapod-python`. + ## Creating a source A **source** is the entry point for data in an Orcapod pipeline. The simplest way to diff --git a/docs/index.md b/docs/index.md index a160250ef..5fa0b142a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,8 +22,15 @@ In an environment not managed by uv, use `pip install orcapod` instead. A plain `uv add orcapod` installs the latest stable release; to try a release candidate, name it, for example `uv add "orcapod==0.4.0rc1"`. -`0.3.0` is the first release on PyPI since `0.1.4`; `0.2.0` was never published to PyPI. -Tables written by `0.2.0` or earlier are not read by `0.3.0`: see +No release after `0.1.4` is available on PyPI yet: `0.2.0` was never published, and `0.3.0` +was withdrawn on 2026-11-17. The next release is `0.4.0`; `uv add orcapod` installs it once +it is out. Until then, install the development version from the repository: + +```bash +uv add git+https://github.com/metamorphic-labs/orcapod-python +``` + +Tables written by `0.2.0` or earlier are not read by this version: see `CHANGELOG.md` in the repository, *Upgrading from 0.2.0* (it also covers `0.1.4`). diff --git a/docs/reference/golden-hashes.md b/docs/reference/golden-hashes.md index add50556d..ec5994b69 100644 --- a/docs/reference/golden-hashes.md +++ b/docs/reference/golden-hashes.md @@ -14,9 +14,15 @@ again, or writes a second copy next to the first. A **golden entry** is one named case and the exact value Orcapod computes for it, for example the `semantic` entry `value.uuid.nil`, whose value is `semantic_v1:...`. The golden test computes every entry again from the code on every CI run. A **data context version** -(today `v1`, key `std:v1:default`, first shipped in Orcapod 0.3) names one generation of -hashing. A hash change that is wanted on purpose starts a new data context version. It never -edits a released value. +(today `v1`, key `std:v1:default`) names one generation of hashing. A hash change that is +wanted on purpose starts a new data context version. It never edits a released value. + +!!! note "v1 is open until 0.4.0" + Orcapod 0.3.0 first shipped `v1` and was withdrawn on 2026-11-17, before anyone used it + (ITL-1255). A withdrawn release freezes nothing, so no `v1` value is released today: until + 0.4.0, a change to a `v1` value is made with the developer's approval of the exact list of + entries that move, each explained. 0.4.0 freezes `v1`. See + [Withdrawing a release](#withdrawing-a-release). ## The pieces at a glance @@ -48,20 +54,20 @@ only at the tags and on PyPI. Three places hold the mechanism: the golden folder of the current data context, the `golden` section of its manifest, and the release pins. The examples below show the state -after a hypothetical patch release 0.3.1 that added one file; digests are shortened. +after a hypothetical patch release 0.4.1 that added one file; digests are shortened. ### Golden files: `tests/test_hashing/golden/data/v1/` ```text tests/test_hashing/golden/data/ v1/ - arrow-01.json # the files of 0.3.0 + arrow-01.json # the files of 0.4.0 datagram-01.json pipeline-01.json schema-01.json semantic-01.json torch-01.json - semantic-02.json # added after 0.3.0: new semantic entries only + semantic-02.json # added after 0.4.0: new semantic entries only ``` - A file is named after the group of cases it pins plus a two-digit counter: @@ -86,12 +92,12 @@ tests/test_hashing/golden/data/ "pipeline-01.json": "e4e4...", "schema-01.json": "315a...", "semantic-01.json": "187c...", "torch-01.json": "99af..."}, "previous": null, "digest": "2bc7..."}, - {"date": "2026-11-16", "release": "0.3.0", "added": {}, + {"date": "2026-11-30", "release": "0.4.0", "added": {}, "previous": "2bc7...", "digest": "d002..."}, - {"date": "2026-11-24", "release": null, + {"date": "2026-12-02", "release": null, "added": {"semantic-02.json": "e810..."}, "previous": "d002...", "digest": "d003..."}, - {"date": "2026-12-01", "release": "0.3.1", "added": {}, + {"date": "2026-12-09", "release": "0.4.1", "added": {}, "previous": "d003...", "digest": "d004..."} ] } @@ -111,13 +117,18 @@ tests/test_hashing/golden/data/ ```json {"v1": {"manifest": "b249...", - "releases": {"0.3.0": "d002...", "0.3.1": "d004..."}}} + "releases": {"0.4.0": "d002...", "0.4.1": "d004..."}, + "withdrawn": {"0.3.0": {"date": "2026-11-17", "reason": "Withdrawn before ...", + "manifest": "18e7...", "revision": "6cdd..."}}}} ``` - `manifest` pins the rest of `v1.json` (the hashers, `definitions`, `libraries`, `previous`, `released_in`). It is `null` while the data context is open and is set once, at the data context's first release. - `releases` gains one line per library release: the digest of that release's revision. +- `withdrawn` (optional) holds one record per withdrawn release: the date, the reason, and + the `manifest` pin and release revision digest (`revision`) that release shipped. A + withdrawn release has no `releases` line and no release revision, so it freezes nothing. ### Digest definitions @@ -177,6 +188,30 @@ edit and the generator refuses to write over it. 4. The tag and the PyPI wheel and sdist, which carry `v1.json` and `released_manifests.json`, are records of what shipped, outside the repository. +Every published version needs the release step, a pre-release included: the release gate +refuses to tag a version without it. So the first version of a data context published on +PyPI freezes it; for `v1`, publishing `0.4.0rc1` would freeze `v1` at the release candidate. + +### Withdrawing a release + +A release is withdrawn only by the developer's decision, when nobody has used it. One +release has been: 0.3.0, withdrawn on 2026-11-17 (ITL-1255), so that `v1` is frozen at 0.4.0 +instead, after the open questions that can move a golden value are settled. The developer +withdraws the version from PyPI (yanked or deleted) and deletes its tag and GitHub Release; in +the repository: + +1. The release revision is taken out of the golden history and the open revisions after it + are chained again (`store.withdraw_release`, which only takes the last release). The + golden files are not touched. +2. Its pins move to a `withdrawn` record in `released_manifests.json`, with the date and the + reason. Without a release left, `released_in` and the `manifest` pin become `null`: the + data context is open again, and every file it listed can change by the approved-change + procedure (`--remove`, then `--add`). +3. The version is never released again: `--release` and the release gate refuse it, and PyPI + never takes a version twice. +4. The tag check compares the release's tag, while it exists, with the record instead of with + HEAD, so it passes before and after the tag is deleted. + ### Starting a new data context version Within `v1` a change to a released golden value is refused, with no exemption: also not for @@ -217,6 +252,7 @@ of the whole tree is caught only by records outside it, the tags and PyPI. | 16 | A release tag is moved or deleted | deliberate | Tag protection, PyPI | GitHub refuses it; PyPI never accepts a second upload of a version | | 17 | The checks themselves are edited to pass | deliberate | Review only | nothing automatic: see the residual risks | | 18 | `main` is force-pushed with rewritten history | deliberate | Branch protection | outside this mechanism | +| 19 | A release is recorded as withdrawn to free its files | deliberate | Tag check, review, PyPI | a record that does not name exactly the pins its tag shipped fails the tag check; a record that does is a visible decision in review, and the version stays on PyPI unless it was withdrawn there | ## Each component in detail @@ -294,8 +330,8 @@ PyPI protect everything against a rewrite of the tree. `scripts/check_golden_tags.py --release-version X.Y.Z`, a step of the Release workflow's build job before the tag is made; tested by `tests/test_check_golden_tags.py` -- **Checks:** HEAD's `released_manifests.json` pins release `X.Y.Z` of the current data - context, its `manifest` pin is set, and the pinned digest is the release revision of +- **Checks:** `X.Y.Z` is not a withdrawn release; HEAD's `released_manifests.json` pins + release `X.Y.Z` of the current data context, its `manifest` pin is set, and the pinned digest is the release revision of `X.Y.Z`, which is the last revision of HEAD's golden history: a golden file added after the release step would ship unreleased, so such a commit is not tagged. It fails without git. @@ -313,9 +349,13 @@ rewrote an earlier release is refused); tested by `tests/test_check_golden_tags. the current data context (the one manifest at HEAD): every golden file listed by the revisions up to that release exists in HEAD with the bytes it has at the tag; those revisions are unchanged in HEAD's history; and the pins of the data context at the tag (the - manifest pin and every `releases` line) are unchanged in HEAD. -- **Protects against:** a full rewrite of files, chain and pins inside the tree (14, 15). - This is the anchor outside the tree. + manifest pin and every `releases` line) are unchanged in HEAD. For a tag whose release + HEAD records as withdrawn, it checks instead that the record's `revision` and `manifest` + are the release digest and manifest pin the tag shipped; once the tag is deleted there is + nothing to compare. +- **Protects against:** a full rewrite of files, chain and pins inside the tree (14, 15), and + a withdrawn record that does not describe the release it names (19). This is the anchor + outside the tree. - **Relies on:** protected tags and history. In CI (`CI=true`) it fails, never skips, when git, the history (a shallow clone) or the tags are missing; outside CI it skips with a message. With no release tag of the current data context it passes with nothing to check. @@ -351,7 +391,7 @@ so the bytes that are hashed are the bytes that were committed (4). | Risk or assumption | Why it matters | What covers it | | --- | --- | --- | -| Git history and `v*` tags are protected on both repositories | The tag check trusts the tags | The `protect-release-tags` ruleset on both repositories (in place since 2026-11-15) and branch protection | +| Git history and `v*` tags are protected on both repositories | The tag check trusts the tags | The `protect-release-tags` ruleset on both repositories (in place since 2026-11-15) and branch protection; the one exception is the tag of the withdrawn 0.3.0, deleted by the developer | | The checks themselves can be edited (17) | A weakened check passes | Review: changes to these tests and scripts get explicit review | | Golden values are computed only with the `uv.lock` versions | A user's newer pyarrow, polars or numpy could hash differently unnoticed | ITL-1151: CI against the lowest and highest allowed dependency versions | | A hash with no golden entry is not protected | Coverage is only as wide as `cases.py` | Add cases whenever a new stored or embedded hash appears | @@ -365,6 +405,11 @@ check inside the repository can stop; the PyPI artifacts remain the record of wh ## Rules - A released golden file never changes, and is never removed or renamed. +- `v1` is open until 0.4.0 (0.3.0 was withdrawn on 2026-11-17): until then, a change to a + `v1` value needs the developer's approval of the exact list of entries that move, each + explained. Never edit or regenerate a golden file to make a test pass. +- A withdrawn release freezes nothing; its record stays under `withdrawn`, and its version is + never released again. - New golden values can be added in any release, a patch included, with `generate_golden_hashes.py`. - No exemption: any change to a released golden value, including one caused by a logical diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1693c4b67..221c81b48 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -312,7 +312,9 @@ Reading a Delta table yourself with `deltalake.DeltaTable(...).to_pyarrow_table( - **`pygraphviz` fails to build** (`fatal error: 'graphviz/cgraph.h' file not found`). You are installing a version of Orcapod older than 0.2, which required the Graphviz - development headers. Install Orcapod 0.2 or newer. + development headers. Install Orcapod 0.2 or newer. Until 0.4.0 is released, a plain + `uv add orcapod` installs 0.1.4 (0.3.0 was withdrawn): install the development version, + `uv add git+https://github.com/metamorphic-labs/orcapod-python`. - **Python version.** Orcapod needs Python 3.11 or newer. - **A release candidate is not installed.** `uv add orcapod` (like `pip install orcapod`) takes the latest stable release and skips pre-releases. Name the release candidate: diff --git a/docs/tutorial/00-setup.md b/docs/tutorial/00-setup.md index 4106a2263..fbc505c53 100644 --- a/docs/tutorial/00-setup.md +++ b/docs/tutorial/00-setup.md @@ -29,7 +29,9 @@ pip install orcapod If your workshop organiser asked you to install a release candidate, name it: `uv add "orcapod==0.4.0rc1"` (a plain `uv add orcapod` takes the latest stable release). For the development version, replace `orcapod` with -`git+https://github.com/metamorphic-labs/orcapod-python.git` in either command. +`git+https://github.com/metamorphic-labs/orcapod-python.git` in either command. Until 0.4.0 +is released, use one of these: PyPI has no current stable release (0.3.0 was withdrawn), so a +plain `uv add orcapod` installs 0.1.4, which this tutorial does not cover. The tutorial needs nothing beyond this. Orcapod already depends on `pandas`, `polars` and `pyarrow`, which the samples use. diff --git a/tests/test_hashing/golden/README.md b/tests/test_hashing/golden/README.md index a1749c496..9c8431920 100644 --- a/tests/test_hashing/golden/README.md +++ b/tests/test_hashing/golden/README.md @@ -13,6 +13,11 @@ In short: `src/orcapod/contexts/released_manifests.json`. - A file listed by a released revision never changes. New values go into new files, in any release. A change to a released value needs a new data context version. +- Data context v1 is open until 0.4.0: 0.3.0 was withdrawn on 2026-11-17 (ITL-1255). Its + release revision is out of the history, and the pins it shipped are kept under `withdrawn` + in `released_manifests.json`, with the date and the reason. Until 0.4.0 a change to a v1 + value needs the developer's approval of the exact list of entries that move, each + explained (`--remove`, then `--add`); never regenerate to make a test pass. | File | Role | | --- | --- | @@ -23,4 +28,5 @@ In short: | `test_golden_store.py` | The rules and the generator, on copies of the tree. | `tests/test_contexts/test_data_context_v1.py` checks the repository's history and pins, and -`scripts/check_golden_tags.py` (a CI step) checks HEAD against every release tag. +`scripts/check_golden_tags.py` (a CI step) checks HEAD against every release tag, and the tag +of a withdrawn release against its record. From c3ceaea9e12318ca4655c6df87fb5f601466ec2f Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 23:16:31 -0800 Subject: [PATCH 3/4] test(contexts): the withdrawal test holds after the next release step (ITL-1255) The open-state assertions apply only while v1 has no release, so the release step of 0.4.0 keeps the test passing; a test runs the release step on a copy of the repository tree and checks the withdrawn record is kept. Co-Authored-By: Claude Opus 5.5 --- tests/test_contexts/test_data_context_v1.py | 37 +++++++++++++++++---- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/tests/test_contexts/test_data_context_v1.py b/tests/test_contexts/test_data_context_v1.py index baa8fc1b3..1aaa25004 100644 --- a/tests/test_contexts/test_data_context_v1.py +++ b/tests/test_contexts/test_data_context_v1.py @@ -25,6 +25,7 @@ ) from orcapod.semantic_types.universal_converter import UniversalTypeConverter from tests.test_hashing.golden import store +from tests.test_hashing.golden.generate_golden_hashes import main CONTEXTS_DIR = Path(str(resources.files("orcapod.contexts"))) MANIFEST_DIR = CONTEXTS_DIR / "data" @@ -146,15 +147,37 @@ def test_0_3_0_is_recorded_as_withdrawn_with_the_pins_it_shipped() -> None: ) -def test_v1_is_open_until_0_4_0() -> None: - """No release of v1 stands: no manifest pin, no releases line, no release revision.""" +def test_the_withdrawn_0_3_0_freezes_nothing() -> None: + """0.3.0 is neither a releases line nor a release revision of v1. + + Until the next release v1 is open: no manifest pin, no releases line, no release + revision. The release step of 0.4.0 (or of any version published before it) freezes v1 + again and keeps this test passing. + """ pin = _pins()["v1"] - assert pin["manifest"] is None - assert pin["releases"] == {} - assert _manifest("v1")["released_in"] is None history = _history("v1") - assert [revision["release"] for revision in history] == [None] * len(history) - assert store.released_files(history) == set() + assert "0.3.0" not in pin["releases"] + assert "0.3.0" not in [revision["release"] for revision in history] + assert _manifest("v1")["released_in"] != "0.3.0" + if not pin["releases"]: + assert pin["manifest"] is None + assert _manifest("v1")["released_in"] is None + assert [revision["release"] for revision in history] == [None] * len(history) + assert store.released_files(history) == set() + + +def test_releasing_after_the_withdrawal_keeps_the_record(tmp_path: Path) -> None: + """The release step on a copy of the repository tree freezes v1 and keeps the record.""" + store.copy_tree(store.PROJECT_ROOT, tmp_path, "v1") + withdrawn = _pins()["v1"]["withdrawn"] + released = set(_pins()["v1"]["releases"]) + next_release = "99.0.0" + main(["--root", str(tmp_path), "--release", next_release]) + pin = store.read_json(store.pins_path(tmp_path))["v1"] + assert set(pin["releases"]) == {*released, next_release} + assert pin["manifest"] is not None + assert pin["withdrawn"] == withdrawn + assert store.tree_problems(tmp_path, "v1") == [] # --------------------------------------------------------------------------- From 6c2028fafdee0c2c7e1ed7d6cd5afa8d784904ce Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 23:31:29 -0800 Subject: [PATCH 4/4] docs: install commands use the repository until 0.4.0 (ITL-1255) Until 0.4.0 is on PyPI a plain uv add orcapod installs 0.1.4, so the install blocks of the README, the index, the getting-started guide and the tutorial setup install the development version, and say that uv add orcapod installs the release once 0.4.0 is out. Co-Authored-By: Claude Opus 5.5 --- README.md | 22 +++++++++------------- docs/getting-started.md | 10 +++++----- docs/index.md | 22 +++++++++------------- docs/tutorial/00-setup.md | 15 +++++++-------- 4 files changed, 30 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 408a38154..5992380bc 100644 --- a/README.md +++ b/README.md @@ -11,28 +11,24 @@ provenance token. ## Installation -Orcapod supports Python 3.11, 3.12 and 3.13 and is published on PyPI as `orcapod`: +Orcapod supports Python 3.11, 3.12 and 3.13 and is published on PyPI as `orcapod`. +No release after 0.1.4 is available there yet: 0.2.0 was never published, and 0.3.0 was +withdrawn on 2026-11-17. Until 0.4.0 is released, install the development version from the +repository. The recommended way to install it is [uv](https://docs.astral.sh/uv/): `uv add` adds Orcapod to a uv project (start one with `uv init` in a new directory), and `uv run` runs your code in that project's environment: -```bash -uv add orcapod -``` - -In an environment not managed by uv, use `pip install orcapod` instead. A plain -`uv add orcapod` installs the latest stable release; to try a release candidate, name it, -for example `uv add "orcapod==0.4.0rc1"`. - -No release after 0.1.4 is available on PyPI yet: 0.2.0 was never published, and 0.3.0 was -withdrawn on 2026-11-17. The next release is 0.4.0; `uv add orcapod` installs it once it is -out. Until then, install the development version from the repository: - ```bash uv add git+https://github.com/metamorphic-labs/orcapod-python ``` +In an environment not managed by uv, use +`pip install git+https://github.com/metamorphic-labs/orcapod-python` instead. Once 0.4.0 is +out, `uv add orcapod` (or `pip install orcapod`) installs the latest stable release; to try a +release candidate, name it, for example `uv add "orcapod==0.4.0rc1"`. + Tables written by 0.2.0 or earlier are not read by this version: see [Upgrading from 0.2.0](https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md#upgrading-from-020) (it also covers 0.1.4). diff --git a/docs/getting-started.md b/docs/getting-started.md index ee455df46..3b8de9567 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -11,15 +11,15 @@ with `uv init` (in a new directory), add Orcapod to it, and run your scripts wit ```bash uv init -uv add orcapod +uv add git+https://github.com/metamorphic-labs/orcapod-python uv run python my_pipeline.py ``` -In an environment not managed by uv, `pip install orcapod` installs it instead. +In an environment not managed by uv, `pip install git+https://github.com/metamorphic-labs/orcapod-python` installs it instead. -Until 0.4.0 is released, PyPI has no current version (0.3.0 was withdrawn, and a plain -`uv add orcapod` would install 0.1.4): add the development version instead, -`uv add git+https://github.com/metamorphic-labs/orcapod-python`. +Until 0.4.0 is released, these commands install the development version from the repository: +PyPI has no current version (0.3.0 was withdrawn, and a plain `uv add orcapod` would install +0.1.4). Once 0.4.0 is out, `uv add orcapod` (or `pip install orcapod`) installs it. ## Creating a source diff --git a/docs/index.md b/docs/index.md index 5fa0b142a..9b4b50887 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,28 +8,24 @@ content-addressable, and reproducible by design. ## Installation Orcapod supports Python 3.11, 3.12 and 3.13 and is published on PyPI as `orcapod`, under the -MIT License: +MIT License. +No release after `0.1.4` is available there yet: `0.2.0` was never published, and `0.3.0` was +withdrawn on 2026-11-17. Until `0.4.0` is released, install the development version from the +repository. The recommended way to install it is [uv](https://docs.astral.sh/uv/): `uv add` adds Orcapod to a uv project (start one with `uv init` in a new directory), and `uv run` runs your code in that project's environment: -```bash -uv add orcapod -``` - -In an environment not managed by uv, use `pip install orcapod` instead. A plain -`uv add orcapod` installs the latest stable release; to try a release candidate, name it, -for example `uv add "orcapod==0.4.0rc1"`. - -No release after `0.1.4` is available on PyPI yet: `0.2.0` was never published, and `0.3.0` -was withdrawn on 2026-11-17. The next release is `0.4.0`; `uv add orcapod` installs it once -it is out. Until then, install the development version from the repository: - ```bash uv add git+https://github.com/metamorphic-labs/orcapod-python ``` +In an environment not managed by uv, use +`pip install git+https://github.com/metamorphic-labs/orcapod-python` instead. Once `0.4.0` is +out, `uv add orcapod` (or `pip install orcapod`) installs the latest stable release; to try a +release candidate, name it, for example `uv add "orcapod==0.4.0rc1"`. + Tables written by `0.2.0` or earlier are not read by this version: see `CHANGELOG.md` in the repository, *Upgrading from 0.2.0* (it also covers `0.1.4`). diff --git a/docs/tutorial/00-setup.md b/docs/tutorial/00-setup.md index fbc505c53..6d2eebd92 100644 --- a/docs/tutorial/00-setup.md +++ b/docs/tutorial/00-setup.md @@ -14,7 +14,7 @@ new directory, and `uv add` adds Orcapod to it): ```bash mkdir orcapod-workshop && cd orcapod-workshop uv init -uv add orcapod +uv add git+https://github.com/metamorphic-labs/orcapod-python ``` Without uv, with `pip` in a virtual environment: @@ -23,15 +23,14 @@ Without uv, with `pip` in a virtual environment: mkdir orcapod-workshop && cd orcapod-workshop python -m venv .venv source .venv/bin/activate # on Windows: .venv\Scripts\activate -pip install orcapod +pip install git+https://github.com/metamorphic-labs/orcapod-python ``` -If your workshop organiser asked you to install a release candidate, name it: -`uv add "orcapod==0.4.0rc1"` (a plain `uv add orcapod` takes the latest stable release). For -the development version, replace `orcapod` with -`git+https://github.com/metamorphic-labs/orcapod-python.git` in either command. Until 0.4.0 -is released, use one of these: PyPI has no current stable release (0.3.0 was withdrawn), so a -plain `uv add orcapod` installs 0.1.4, which this tutorial does not cover. +Both install the development version from the repository: until 0.4.0 is released, PyPI has +no current stable release (0.3.0 was withdrawn), so a plain `uv add orcapod` installs 0.1.4, +which this tutorial does not cover. If your workshop organiser asked you to install a release +candidate, name it instead: `uv add "orcapod==0.4.0rc1"`. Once 0.4.0 is out, `uv add orcapod` +(or `pip install orcapod`) installs the latest stable release. The tutorial needs nothing beyond this. Orcapod already depends on `pandas`, `polars` and `pyarrow`, which the samples use.