From 228b18c162d55a8fe9f5cbabb7a153c4d7aacdb2 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 22:47:05 -0800 Subject: [PATCH 1/8] docs(release): release orcapod-python from metamorphic-labs, a public repository (ITL-1193) - RELEASING.md: the developer runs the Release workflow on metamorphic-labs from main; no fast-forward push to nauticalab and no tag fetched back (history note: 0.3.0 and earlier were cut from nauticalab). Describes what the Linear release jobs do now that they run, and the step that keeps the first run from completing an empty Linear release. A tag left by a failed build cannot be deleted under protect-release-tags: release the next version. - CLAUDE.md, .zed/rules, AGENT_COORDINATION.md: the repository is public; nothing private goes into a commit, PR, issue or comment; agents never run the Release workflow, tag, or touch settings, secrets, environments, rulesets or visibility. - .coderabbit.yaml: review context from this repository only (learnings, issues and pull requests local; linked repositories, automatic linking, web search, Linear, Jira and MCP off; chat for organization members only). - _license-check.yml, run-objective-tests.yml: explicit read-only token. - README.md, pyproject.toml project URLs, tutorial setup page, golden-hashes reference: metamorphic-labs/orcapod-python is the project's home. Co-Authored-By: Claude Opus 5.5 --- .coderabbit.yaml | 31 +++ .github/workflows/_license-check.yml | 4 + .github/workflows/run-objective-tests.yml | 4 + .zed/rules | 22 ++- AGENT_COORDINATION.md | 10 + CLAUDE.md | 22 ++- README.md | 26 +-- RELEASING.md | 221 +++++++++++----------- changelog.d/ITL-1193.md | 6 + docs/reference/golden-hashes.md | 5 +- docs/tutorial/00-setup.md | 4 +- pyproject.toml | 8 +- 12 files changed, 218 insertions(+), 145 deletions(-) create mode 100644 changelog.d/ITL-1193.md diff --git a/.coderabbit.yaml b/.coderabbit.yaml index c341380db..c8cc37b68 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -12,3 +12,34 @@ reviews: enabled: true base_branches: - ".*" +# This repository is public (ITL-1193). CodeRabbit takes review context from this +# repository only: learnings, issues and pull requests of other repositories in the +# organization, linked repositories, web search, and the Linear, Jira and MCP knowledge +# sources are all off, so that nothing from a private repository or tracker is quoted in +# a public review. On a public repository "auto" already means local or disabled; the +# explicit values hold whatever the visibility or the UI settings are. +knowledge_base: + web_search: + enabled: false + learnings: + scope: local + issues: + scope: local + pull_requests: + scope: local + automatic_linking_mode: disabled + linked_repositories: [] + jira: + usage: disabled + linear: + usage: disabled + mcp: + usage: disabled +chat: + # Only organization members can prompt CodeRabbit in a comment thread. + allow_non_org_members: false + integrations: + jira: + usage: disabled + linear: + usage: disabled diff --git a/.github/workflows/_license-check.yml b/.github/workflows/_license-check.yml index e91dc2acb..c513017c5 100644 --- a/.github/workflows/_license-check.yml +++ b/.github/workflows/_license-check.yml @@ -9,6 +9,10 @@ on: type: string default: '' +# Read-only token, whatever the repository default is (ITL-1193). +permissions: + contents: read + jobs: license-check: name: License check diff --git a/.github/workflows/run-objective-tests.yml b/.github/workflows/run-objective-tests.yml index 3df72ceff..0a031c359 100644 --- a/.github/workflows/run-objective-tests.yml +++ b/.github/workflows/run-objective-tests.yml @@ -6,6 +6,10 @@ on: pull_request: workflow_dispatch: # Allows manual triggering +# Read-only token, whatever the repository default is (ITL-1193). +permissions: + contents: read + jobs: test: runs-on: ubuntu-latest diff --git a/.zed/rules b/.zed/rules index ac2e76dd2..e4f13cab4 100644 --- a/.zed/rules +++ b/.zed/rules @@ -238,14 +238,20 @@ resolves several issues uses its primary issue's id). ## Releasing and the public repository -Developer decisions, November 12, 2026 (ITL-1007); the full procedure is RELEASING.md. - -- All development, review and CI happen on metamorphic-labs/orcapod-python. The public - nauticalab/orcapod-python receives main only at release points, by **fast-forward push** - (never a squash, never a pull request), and runs the Release workflow. -- An agent never pushes to nauticalab, adds a remote for it, creates or pushes a tag, runs the - Release workflow, or touches a setting, secret or environment there. The push happens only on - the developer's explicit go. The v0.2.0 tag is never pushed. +Developer decisions, November 16, 2026 (ITL-1193); the full procedure is RELEASING.md. + +- metamorphic-labs/orcapod-python is the one repository: development, review, CI and + releases. The developer cuts a release by running the Release workflow there, from main. + nauticalab/orcapod-python cut the releases up to 0.3.0 and is being retired (made + private): never push to it, add a remote for it, or point a link at it as the project's home. +- The repository is public. Nothing private goes into a commit, branch name, pull request, + issue, review or comment: no internal hostname, address or path, no content of another + private repository, no credential or secret value, no Linear text that is not about this + repository, and nothing about the full EDI dataset (its location, storage, projects or + tables). +- An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, + secret, environment, ruleset or the visibility of the repository. The v0.2.0 tag stays as + it is. - Linear, Codecov and SpiralDB jobs run only when github.repository == 'metamorphic-labs/orcapod-python'; lint.yml runs only on nauticalab. diff --git a/AGENT_COORDINATION.md b/AGENT_COORDINATION.md index 4bf29fceb..320571035 100644 --- a/AGENT_COORDINATION.md +++ b/AGENT_COORDINATION.md @@ -136,6 +136,16 @@ developer. _Posted by a Claude Code agent on behalf of @eywalker._ ``` +- **The repository is public** (ITL-1193). Anyone can read every commit, branch name, PR, + issue, review, comment and Actions log. An agent's comment, reply, review, PR text and + commit message hold nothing private: no internal hostname, address or home-directory path, + no content of another private repository (its name, files, PRs or learnings), no credential + or secret value (not even a part of one), no Linear text that is not about this repository, + and nothing about the full EDI dataset (its location, storage, projects or tables). Such + material goes to the coordinator through the orchestration commands, or into a Linear + comment. A bot comment that quotes such material (a CodeRabbit "Learnings used" block, a + Linear linkback) is reported to the coordinator by its PR number and comment id, without + quoting it; only the developer deletes it. - **Permission blocks.** If the worker's own permission check denies a push or another external write, the worker holds and escalates. Neither the worker nor the coordinator routes around it; the developer approves it in the worker's terminal. diff --git a/CLAUDE.md b/CLAUDE.md index 3c94b710b..0e6619917 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -247,14 +247,20 @@ resolves several issues uses its primary issue's id). ## Releasing and the public repository -Developer decisions, November 12, 2026 (ITL-1007); the full procedure is `RELEASING.md`. - -- All development, review and CI happen on `metamorphic-labs/orcapod-python`. The public - `nauticalab/orcapod-python` receives `main` only at release points, by **fast-forward push** - (never a squash, never a pull request), and runs the Release workflow. -- An agent never pushes to `nauticalab`, adds a remote for it, creates or pushes a tag, runs the - Release workflow, or touches a setting, secret or environment there. The push happens only on - the developer's explicit go. The `v0.2.0` tag is never pushed. +Developer decisions, November 16, 2026 (ITL-1193); the full procedure is `RELEASING.md`. + +- `metamorphic-labs/orcapod-python` is the one repository: development, review, CI and + releases. The developer cuts a release by running the Release workflow there, from `main`. + `nauticalab/orcapod-python` cut the releases up to 0.3.0 and is being retired (made + private): never push to it, add a remote for it, or point a link at it as the project's home. +- The repository is public. Nothing private goes into a commit, branch name, pull request, + issue, review or comment: no internal hostname, address or path, no content of another + private repository, no credential or secret value, no Linear text that is not about this + repository, and nothing about the full EDI dataset (its location, storage, projects or + tables). +- An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, + secret, environment, ruleset or the visibility of the repository. The `v0.2.0` tag stays as + it is. - Linear, Codecov and SpiralDB jobs run only when `github.repository == 'metamorphic-labs/orcapod-python'`; `lint.yml` runs only on `nauticalab`. diff --git a/README.md b/README.md index 475e9812c..75d476d5c 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ uv add orcapod 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 -[Upgrading from 0.2.0](https://github.com/nauticalab/orcapod-python/blob/main/CHANGELOG.md#upgrading-from-020) +[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). Optional features are installed as extras: @@ -92,19 +92,19 @@ session. ## Documentation -- [Getting Started](https://github.com/nauticalab/orcapod-python/blob/main/docs/getting-started.md): +- [Getting Started](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/getting-started.md): sources, streams and function pods, step by step. -- [Tutorial](https://github.com/nauticalab/orcapod-python/blob/main/docs/tutorial/index.md): +- [Tutorial](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/tutorial/index.md): a self-paced course in eleven short parts, from a first stream to a stored, re-runnable pipeline over files, with exercises. -- [Concepts](https://github.com/nauticalab/orcapod-python/tree/main/docs/concepts): sources, +- [Concepts](https://github.com/metamorphic-labs/orcapod-python/tree/main/docs/concepts): sources, streams, function pods, operators, pipelines and jobs, identity and hashing, file types, arrays and your own data types. -- Reference: [Hashing](https://github.com/nauticalab/orcapod-python/blob/main/docs/reference/hashing.md) - and [Golden hashes](https://github.com/nauticalab/orcapod-python/blob/main/docs/reference/golden-hashes.md). -- [Troubleshooting](https://github.com/nauticalab/orcapod-python/blob/main/docs/troubleshooting.md): +- Reference: [Hashing](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/reference/hashing.md) + and [Golden hashes](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/reference/golden-hashes.md). +- [Troubleshooting](https://github.com/metamorphic-labs/orcapod-python/blob/main/docs/troubleshooting.md): common errors, their causes and fixes. -- [CHANGELOG](https://github.com/nauticalab/orcapod-python/blob/main/CHANGELOG.md): what +- [CHANGELOG](https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md): what changed in each release, with upgrade notes. ## Status @@ -114,7 +114,7 @@ Orcapod is before version 1.0. In 0.3.0: - **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 - [Golden hashes](https://github.com/nauticalab/orcapod-python/blob/main/docs/reference/golden-hashes.md). + [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 may change in 0.4, and results computed from them may then be computed again. Using one issues `ProvisionalHashWarning` once per @@ -122,7 +122,7 @@ Orcapod is before version 1.0. In 0.3.0: - **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 - [Upgrading from 0.2.0](https://github.com/nauticalab/orcapod-python/blob/main/CHANGELOG.md#upgrading-from-020) + [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 SpiralDB database refuses every function node when it is built. Use `InMemoryArrowDatabase` @@ -154,11 +154,11 @@ uv run pytest tests/ The PostgreSQL integration tests are skipped unless asked for (`uv run pytest -m postgres --postgres`) and need a running PostgreSQL server, reached through the standard `PG*` environment variables; see -[the workflow that runs them](https://github.com/nauticalab/orcapod-python/blob/main/.github/workflows/run-postgres-tests.yml). +[the workflow that runs them](https://github.com/metamorphic-labs/orcapod-python/blob/main/.github/workflows/run-postgres-tests.yml). Releases are cut by the GitHub Actions Release workflow; see -[RELEASING.md](https://github.com/nauticalab/orcapod-python/blob/main/RELEASING.md). +[RELEASING.md](https://github.com/metamorphic-labs/orcapod-python/blob/main/RELEASING.md). ## License Orcapod is released under the -[MIT License](https://github.com/nauticalab/orcapod-python/blob/main/LICENSE). +[MIT License](https://github.com/metamorphic-labs/orcapod-python/blob/main/LICENSE). diff --git a/RELEASING.md b/RELEASING.md index 72ce2ae21..0f99b601f 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -7,22 +7,26 @@ This document describes how to cut a release of `orcapod`. Orcapod is published on public PyPI as [`orcapod`](https://pypi.org/project/orcapod/), under the MIT License (developer decision, 2026-11-10; the license is applied from `0.2.0`). Users install it with `pip install orcapod` or `uv add orcapod`. `0.2.0` was cut as a tag only -(developer decision, 2026-11-10); `0.3.0` is the first release published to PyPI from this -repository. - -Two repositories take part (developer decision, 2026-11-12, ITL-1007): - -| Repository | Role | -|---|---| -| `metamorphic-labs/orcapod-python` | **All development**: branches, pull requests, review, CI, Linear integration, the design log. | -| `nauticalab/orcapod-python` (public) | **Releases only**: receives `main` by fast-forward push at a release point, and runs the Release workflow. | - -The Release workflow (`.github/workflows/release.yml`) is the only publishing route. It runs -only when dispatched by hand **on `nauticalab/orcapod-python`**, uploads to TestPyPI first and then -to PyPI, and authenticates to both through OIDC trusted publishing: the workflow uses no API -token. That requires, on each index, a trusted publisher for the `orcapod` project naming owner -`nauticalab`, repository `orcapod-python`, workflow `release.yml` and environment `testpypi` -(TestPyPI) or `pypi` (PyPI); see *One-time setup* below. +(developer decision, 2026-11-10). + +One repository does everything (developer decision, 2026-11-16, ITL-1193): +`metamorphic-labs/orcapod-python`, a public repository, holds development (branches, pull +requests, review, CI, the Linear integration, the design log) and cuts the releases. + +The Release workflow (`.github/workflows/release.yml`) is the only publishing route. The +developer dispatches it by hand on `metamorphic-labs/orcapod-python`, from `main`. It uploads +to TestPyPI first and then to PyPI, and authenticates to both through OIDC trusted publishing: +the workflow uses no API token. That requires, on each index, a trusted publisher for the +`orcapod` project naming owner `metamorphic-labs`, repository `orcapod-python`, workflow +`release.yml` and environment `testpypi` (TestPyPI) or `pypi` (PyPI); see *One-time setup* +below. An agent never runs the Release workflow, creates or pushes a tag, or changes a +setting, secret or environment. + +**History.** Up to and including `0.3.0` (2026-11-17), releases were cut from +`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. ## Branching Model @@ -32,7 +36,7 @@ token. That requires, on each index, a trusted publisher for the `orcapod` proje ## Before You Cut -Do these on `metamorphic-labs` `main` before anything is pushed: +Do these on `main` before the Release workflow runs: 1. **Update `CHANGELOG.md`** in a release pull request, the only kind of pull request that edits it. Feature pull requests add `changelog.d/.md` fragments instead (see @@ -78,26 +82,28 @@ Do these on `metamorphic-labs` `main` before anything is pushed: 3. **Check that `main` is green** — the `Run Tests` workflow on the commit you are releasing. The Release workflow re-runs the unit tests on Python 3.11, 3.12 and 3.13 and the license check, but not the PostgreSQL or SpiralDB integration jobs. -4. **Check the version is free** — the tag must not exist on origin, and the version must - not exist on PyPI or TestPyPI; neither index allows a version to be uploaded twice, even +4. **Check the version is free** — the tag must not exist on `metamorphic-labs`, and the + version must not exist on PyPI or TestPyPI; neither index allows a version to be uploaded twice, even after it is deleted. Per-release checklists live in `docs/dev/plans/` (for example `2026-11-09-v0.2-release-checklist.md`, `2026-11-15-v0.3-release-checklist.md`). -## Pre-push checklist +## Pre-release checklist -All of these hold before the developer is asked for the go: +All of these hold before the developer runs the Release workflow: -1. **The full suite is green**: `uv run pytest tests/` passes on the commit to be pushed. -2. **The release pull request is merged** on `metamorphic-labs` (`CHANGELOG.md` folded, section - dated, `changelog.d/` fragments deleted). +1. **The full suite is green**: `uv run pytest tests/` passes on the commit to be released. +2. **The release pull request is merged** (`CHANGELOG.md` folded, section dated, + `changelog.d/` fragments deleted). 3. **The golden release step is done**: `contexts/released_manifests.json` has the current data context's `releases` line for this version and a pinned `manifest`, and the golden hash tests and the data context tests pass unchanged. -4. **`main` is green** on `metamorphic-labs`, and `git status` is clean. -5. **The version is free**: the tag does not exist on `nauticalab`, and the version is on - neither PyPI nor TestPyPI. +4. **`main` is green**, and `git status` is clean. +5. **The version is free**: the tag does not exist on `metamorphic-labs`, and the version is + on neither PyPI nor TestPyPI. +6. **The Linear release is named** (see *Linear Release System*): the open release of the + Linear release pipeline has the version `vX.Y.Z`. ## Golden hash values @@ -111,10 +117,10 @@ 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. -- Release tags are protected on both `metamorphic-labs/orcapod-python` and - `nauticalab/orcapod-python`: 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 +- 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. @@ -123,33 +129,21 @@ against are in `docs/reference/golden-hashes.md`. Releases are triggered from the GitHub Actions UI — no manual `git tag` step required. **Do not create the release tag by hand:** the `build` job aborts when the tag already exists -on origin, so a hand-made `vX.Y.Z` tag means that version can no longer be published by the -workflow until the tag is deleted. +on origin, and the ruleset `protect-release-tags` forbids deleting a `v*` tag, so a hand-made +`vX.Y.Z` tag means that version can no longer be published by the workflow. -1. **Push `main` to `nauticalab` as a fast-forward, on the developer's explicit go only.** - A push to a public repository cannot be undone, so no agent does this on its own. - - ``` - git remote add nauticalab https://github.com/nauticalab/orcapod-python.git # once - git fetch nauticalab - git merge-base --is-ancestor nauticalab/main main && echo "fast-forward" # must print it - git push nauticalab main:main # no --force - ``` +1. **Run Release** — go to + **[Actions → Release → Run workflow](https://github.com/metamorphic-labs/orcapod-python/actions/workflows/release.yml)** + in the GitHub UI, keep **Use workflow from** on `main`, enter the version (e.g. `0.4.0`), + optionally enter a branch name (defaults to `main`), and click **Run workflow**. A leading + `v` is stripped automatically. Leave the `skip_tests` checkbox (labelled *Skip the test + jobs …*) unchecked; it is an exception, described in *Skipping the release tests* below. + The developer does this; no agent runs the workflow. - Never a squash, never a pull request: commit ids must stay identical in both repositories, - because the version comes from the tag (`hatch-vcs`). Never push the `v0.2.0` tag (or any - tag): the Release workflow creates the release tag on `nauticalab`. The push also replaces - the workflows `nauticalab` carries (its old `tests.yml` is deleted by it, as `main` removed - that file). +2. **Approve the PyPI deployment** — `publish-pypi` runs in the `pypi` environment, which + requires a reviewer: approve it once `publish-testpypi` has succeeded. -2. **Run Release on `nauticalab`** — go to - **[Actions → Release → Run workflow](https://github.com/nauticalab/orcapod-python/actions/workflows/release.yml)** - in the GitHub UI, enter the version (e.g. `0.3.0`), optionally enter a branch name - (defaults to `main`), and click **Run workflow**. A leading `v` is stripped automatically. - Leave the `skip_tests` checkbox (labelled *Skip the test jobs …*) unchecked; it is an - exception, described in *Skipping the release tests* below. - -3. **CI takes over** — the workflow runs the following jobs automatically: +3. **CI takes over** — the workflow runs the following jobs: ``` validate-branch ─┬─ test ──────────┐ @@ -158,19 +152,12 @@ workflow until the tag is deleted. ``` - Pre-flight: branch validation, then tests on Python 3.11, 3.12 and 3.13 and license check (parallel after validation); the tests are skipped only with `skip_tests` - - Build: normalises version (strips a leading `v`), creates the local tag, builds wheel + sdist with `uv build`, aborts if the tag already exists on origin, pushes the tag, uploads `dist/` as an artifact + - Build: normalises version (strips a leading `v`), checks the golden release step and the release tags, creates the local tag, builds wheel + sdist with `uv build`, aborts if the tag already exists on origin, pushes the tag, uploads `dist/` as an artifact - TestPyPI: in the `testpypi` environment, `uv publish --publish-url https://test.pypi.org/legacy/ dist/*` with an OIDC token (`id-token: write`) — a staging upload - - PyPI: in the `pypi` environment, after TestPyPI succeeds, `uv publish dist/*` with an OIDC token, then creates the GitHub Release for the tag with generated release notes and the dist files attached - - Linear: `linear-sync` starts immediately after build (parallel to publish); `linear-complete` runs after both PyPI publish and linear-sync succeed - -4. **Fetch the tag back into `metamorphic-labs`** once the run has succeeded: - - ``` - git fetch nauticalab --tags - git push origin vX.Y.Z - ``` + - PyPI: in the `pypi` environment, after TestPyPI succeeds and a reviewer approves, `uv publish dist/*` with an OIDC token, then creates the GitHub Release for the tag with generated release notes and the dist files attached + - Linear: `linear-sync` starts immediately after build (parallel to publish); `linear-complete` runs after both PyPI publish and linear-sync succeed (see *Linear Release System*) - `metamorphic-labs` then holds the same tag on the same commit. +The tag is created by the workflow in this repository; there is nothing to fetch back. ## Skipping the release tests @@ -180,13 +167,13 @@ Checked, the `test` jobs (Python 3.11, 3.12 and 3.13) do not run; everything els the license check, the build with its golden checks, the tag, TestPyPI, PyPI and the GitHub Release. Unchecked, the workflow is exactly what it was before the input existed. -This is an exception, for a pinch: the release tests take a long time and repeat what the -development repository already ran. Use it only when all of these hold: +This is an exception, for a pinch: the release tests take a long time and repeat what +`Run Tests` already ran on the same commit. Use it only when all of these hold: -- The exact commit being released (the tip of the **Branch** input on `nauticalab`) has - green required CI on `metamorphic-labs/orcapod-python`: the `Run Tests` workflow on that - commit passed on Python 3.11, 3.12 and 3.13. Check the commit id, not the branch name. -- The pre-push checklist above holds, the full suite included. +- The exact commit being released (the tip of the **Branch** input) has green CI: the + `Run Tests` workflow on that commit passed on Python 3.11, 3.12 and 3.13. Check the commit + id, not the branch name. +- The pre-release checklist above holds, the full suite included. - The developer chose it for this run. An agent never runs the Release workflow, with or without the option. @@ -206,24 +193,33 @@ needs the same. ## One-time setup (only the developer can do this) -On `nauticalab/orcapod-python` and the package indexes; no agent changes settings, secrets or -environments: +On `metamorphic-labs/orcapod-python` and the package indexes; no agent changes settings, +secrets or environments: -1. Create the environments `testpypi` and `pypi` (`Settings → Environments`). +1. The environments `testpypi` and `pypi` (`Settings → Environments`). `pypi` requires a + reviewer. Give both a deployment branch policy that allows `main` only, so that no workflow + on another branch can request a publishing token. A hotfix release still passes it: the + workflow runs from `main` (**Use workflow from**) and only checks out the hotfix branch. 2. On pypi.org and test.pypi.org, an owner of the `orcapod` project opens - *Manage → Publishing* and adds a GitHub trusted publisher with owner `nauticalab`, + *Manage → Publishing* and adds a GitHub trusted publisher with owner `metamorphic-labs`, repository `orcapod-python`, workflow `release.yml` and environment `pypi` (PyPI) or `testpypi` (TestPyPI). An upload from a repository that no trusted publisher names is - rejected, which fails `publish-testpypi` after the tag has been pushed. Remove the entries - that name `metamorphic-labs`, if any. -3. Protect `main` on `nauticalab` (no force push, no deletion). It is written only by the - fast-forward push above. -4. Protect release tags on both `metamorphic-labs/orcapod-python` and - `nauticalab/orcapod-python` with the ruleset `protect-release-tags` (target + rejected, which fails `publish-testpypi` after the tag has been pushed. Registered by the + developer on 2026-11-16. Remove the entries that name `nauticalab` once + `nauticalab/orcapod-python` is retired. +3. `main` is protected by organization rulesets: today their rules are pull requests only, + no force push (non-fast-forward) and no deletion. The rulesets for public repositories + apply once the repository is public; check that they keep these three rules. +4. Release tags are protected with the ruleset `protect-release-tags` (target `refs/tags/v*`; deletion, update, non-fast-forward; no bypass actors), so the golden tag check has a fixed anchor (ITL-946). Done on 2026-11-15. -5. Optional: set `CODECOV_TOKEN` there. The Codecov, SpiralDB and Linear jobs run only on - `metamorphic-labs` and are skipped on `nauticalab`. +5. The `LINEAR_ACCESS_KEY` repository secret, for the Linear jobs (see *Linear Release + System*), and the organization secret `CODECOV_TOKEN`, for the 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. ### SpiralDB integration job @@ -281,12 +277,10 @@ workflow. **Example:** cutting `v0.1.1` from `hotfix/0.1.x`: -0. **Make sure `hotfix/0.1.x` on `nauticalab` points at the commit to release.** The workflow - resolves the **Branch** input only there and tags its tip. If the branch is missing or behind, - fast-forward it (on the developer's explicit go only, never with `--force`): - `git push nauticalab hotfix/0.1.x:hotfix/0.1.x` +0. **Make sure `hotfix/0.1.x` points at the commit to release.** The workflow checks that the + **Branch** input exists in this repository and tags its tip. 1. **Trigger the release workflow** — go to - **[Actions → Release → Run workflow](https://github.com/nauticalab/orcapod-python/actions/workflows/release.yml)** + **[Actions → Release → Run workflow](https://github.com/metamorphic-labs/orcapod-python/actions/workflows/release.yml)** 2. In the **Use workflow from** dropdown, keep `main` selected (so the workflow version includes the `Branch` field — do not select `hotfix/0.1.x` here) 3. Set **Version** to `0.1.1` @@ -305,7 +299,7 @@ failure in a later job leaves the tag behind. |-----------|-------------------|----------| | `test` or `license-check` | Nothing | Fix on `main`, trigger a new run | | `build`, before "Push release tag" | Nothing | Fix, trigger a new run | -| `build`, after "Push release tag" | Tag on origin, no artifact | Delete the tag (`git push origin :refs/tags/vX.Y.Z`), then trigger a new run | +| `build`, after "Push release tag" | Tag on origin, no artifact | The tag cannot be deleted (`protect-release-tags`), and a new run or a re-run stops at the duplicate-tag guard: release the next patch version | | `publish-testpypi` | Tag on origin | Use **Re-run failed jobs** on the same run — do not start a new run, which would fail creating a tag that already exists | | `publish-pypi` | Tag on origin, version on TestPyPI | Use **Re-run failed jobs**. If the upload to PyPI itself partly succeeded, the version is burned: release the next patch version instead | | `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 | @@ -336,20 +330,33 @@ manual version bump is needed. ## Linear Release System -Linear is wired to the development repository only. `release-sync.yml` and the `linear-sync` and -`linear-complete` jobs of `release.yml` run only when -`github.repository == 'metamorphic-labs/orcapod-python'`; on `nauticalab` they are skipped, which -does not block or fail the release (no publish job depends on them). They call -`linear/linear-release-action` and transition the issues in **"Merged"** status to **"Done"**. - -| Trigger | Workflow / Job | Action | Effect | -|---------|---------------|--------|--------| -| Push to `main` (`metamorphic-labs`) | `release-sync.yml / sync` | `sync` (no version) | Associates the merged PR with the open Linear release draft | -| Release workflow `build` succeeds (`metamorphic-labs` only) | `release.yml / linear-sync` | `sync --version ` | Finalises the commit set for the version | -| After `publish-pypi` succeeds (`metamorphic-labs` only) | `release.yml / linear-complete` | `complete --version ` | Marks the release done in Linear | - -Because the Release workflow runs on `nauticalab`, these jobs do not run for a release at all -today; completing the Linear release is a manual step until the developer decides otherwise -(the issue ITL-1007 notes this "needs more thought"). Setup on `metamorphic-labs`: the -`LINEAR_ACCESS_KEY` repo secret (the organisation's Linear access key) and a Linear release -configured in the workspace. +Three jobs call `linear/linear-release-action` (pinned; it runs the Linear Release CLI) with +the `LINEAR_ACCESS_KEY` repository secret, the access key of one Linear release pipeline. Each +runs only when `github.repository == 'metamorphic-labs/orcapod-python'`, so a fork's run skips +it, and none of them can block or undo a publish: no publish job depends on them. Up to +`0.3.0` the two release jobs never ran (the Release workflow ran on `nauticalab`, where they are +skipped) and the Linear release was completed by hand. From the first release cut here they +run. + +| Trigger | Workflow / Job | Command | What it does | +|---------|---------------|---------|--------------| +| Push to `main` | `release-sync.yml / sync` | `sync` (no version) | Scans the commits since the last synced commit for Linear issue ids and pull request numbers, and adds them to the pipeline's open release (today one with no version set) | +| Release workflow `build` succeeds | `release.yml / linear-sync` | `sync --version vX.Y.Z` | Targets the release whose version is `vX.Y.Z`, or **creates** one, and adds the commits since the last synced commit | +| After `publish-pypi` succeeds | `release.yml / linear-complete` | `complete --version vX.Y.Z` | Completes the release whose version is `vX.Y.Z` | + +The workflow only syncs and completes the Linear release; any change of issue status that +comes with a completed release is made by Linear, as the workspace configures it. + +**Before the first run, and every run after it: name the open release.** Every push to `main` +adds its pull request to the open release, which has no version, and moves the scan start to +that commit. A release of `main`'s tip therefore finds no new commit: without a release named +`vX.Y.Z`, `linear-sync` creates an empty `vX.Y.Z` release (or none at all, if the CLI creates +nothing for an empty range), the open release holding the merged pull requests is left as it is, +and `linear-complete` completes the empty release or fails to find one. So, before running the +Release workflow, the developer sets the version of the pipeline's open release to `vX.Y.Z` in +Linear (pre-release checklist, item 6); `linear-sync` then targets it and `linear-complete` +completes it. If a Linear job fails anyway, the release is published; finish the Linear release +by hand (*If a Run Fails Part-Way*). + +Setup: the `LINEAR_ACCESS_KEY` repository secret, holding the access key of the pipeline meant +for this repository's releases. diff --git a/changelog.d/ITL-1193.md b/changelog.d/ITL-1193.md new file mode 100644 index 000000000..ae924d42b --- /dev/null +++ b/changelog.d/ITL-1193.md @@ -0,0 +1,6 @@ +### Changed + +- The project's home is now `metamorphic-labs/orcapod-python`, and releases are cut there. + The package's project URLs (homepage, repository, changelog, issues), the links in + `README.md` and the tutorial's install and download commands point to it. + `nauticalab/orcapod-python`, the release repository up to 0.3.0, is being retired. (ITL-1193) diff --git a/docs/reference/golden-hashes.md b/docs/reference/golden-hashes.md index 6d620c548..add50556d 100644 --- a/docs/reference/golden-hashes.md +++ b/docs/reference/golden-hashes.md @@ -162,9 +162,8 @@ edit and the generator refuses to write over it. ### Releasing (the release pull request) 1. Precondition, in place since 2026-11-15 (developer decision): the repository ruleset - `protect-release-tags` on both `metamorphic-labs/orcapod-python` and - `nauticalab/orcapod-python` targets `refs/tags/v*` with the rules deletion, update and - non-fast-forward and no bypass actors. A `v*` tag can be created (the Release workflow + `protect-release-tags` on `metamorphic-labs/orcapod-python`, where releases are cut, targets + `refs/tags/v*` with the rules deletion, update and non-fast-forward and no bypass actors. A `v*` tag can be created (the Release workflow pushes it) but never moved or deleted. Agents never change repository settings. 2. Run `TZ=UTC uv run python tests/test_hashing/golden/generate_golden_hashes.py --release X.Y.Z` (release dates are UTC days, and the revision's date is read from the local clock). diff --git a/docs/tutorial/00-setup.md b/docs/tutorial/00-setup.md index 5d0fb7cd5..403d51611 100644 --- a/docs/tutorial/00-setup.md +++ b/docs/tutorial/00-setup.md @@ -26,7 +26,7 @@ pip install orcapod ``` If your workshop organiser asked you to install the development version instead, replace -`orcapod` with `git+https://github.com/nauticalab/orcapod-python.git` in either command. +`orcapod` with `git+https://github.com/metamorphic-labs/orcapod-python.git` in either command. The tutorial needs nothing beyond this. Orcapod already depends on `pandas`, `polars` and `pyarrow`, which the samples use. @@ -90,7 +90,7 @@ Download [`workshop_data.py`](workshop_data.py) into your working directory, or the command line: ```bash -curl -fO https://raw.githubusercontent.com/nauticalab/orcapod-python/main/docs/tutorial/workshop_data.py +curl -fO https://raw.githubusercontent.com/metamorphic-labs/orcapod-python/main/docs/tutorial/workshop_data.py ``` Then run it: diff --git a/pyproject.toml b/pyproject.toml index ce7b93091..706b3d3f8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,10 +38,10 @@ classifiers = [ ] [project.urls] -Homepage = "https://github.com/nauticalab/orcapod-python" -Repository = "https://github.com/nauticalab/orcapod-python" -Changelog = "https://github.com/nauticalab/orcapod-python/blob/main/CHANGELOG.md" -Issues = "https://github.com/nauticalab/orcapod-python/issues" +Homepage = "https://github.com/metamorphic-labs/orcapod-python" +Repository = "https://github.com/metamorphic-labs/orcapod-python" +Changelog = "https://github.com/metamorphic-labs/orcapod-python/blob/main/CHANGELOG.md" +Issues = "https://github.com/metamorphic-labs/orcapod-python/issues" [project.optional-dependencies] redis = ["redis>=6.2.0"] From a02e7c33621a0d5ad6b9cd1d26c6d4bab9a78fde Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Mon, 16 Nov 2026 23:30:59 -0800 Subject: [PATCH 2/8] docs(release): a hotfix run leaves the open Linear release alone (ITL-1193) Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 0f99b601f..8b11631c8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -103,7 +103,8 @@ All of these hold before the developer runs the Release workflow: 5. **The version is free**: the tag does not exist on `metamorphic-labs`, and the version is on neither PyPI nor TestPyPI. 6. **The Linear release is named** (see *Linear Release System*): the open release of the - Linear release pipeline has the version `vX.Y.Z`. + Linear release pipeline has the version `vX.Y.Z`. Not for a hotfix run, which leaves the open + release as it is. ## Golden hash values @@ -350,13 +351,22 @@ comes with a completed release is made by Linear, as the workspace configures it **Before the first run, and every run after it: name the open release.** Every push to `main` adds its pull request to the open release, which has no version, and moves the scan start to that commit. A release of `main`'s tip therefore finds no new commit: without a release named -`vX.Y.Z`, `linear-sync` creates an empty `vX.Y.Z` release (or none at all, if the CLI creates -nothing for an empty range), the open release holding the merged pull requests is left as it is, -and `linear-complete` completes the empty release or fails to find one. So, before running the +`vX.Y.Z`, `linear-sync` creates an empty `vX.Y.Z` release (or none, if the CLI creates nothing +for an empty range), the open release holding the merged pull requests is left as it is, and +`linear-complete` completes the empty release or fails to find one. So, before running the Release workflow, the developer sets the version of the pipeline's open release to `vX.Y.Z` in Linear (pre-release checklist, item 6); `linear-sync` then targets it and `linear-complete` completes it. If a Linear job fails anyway, the release is published; finish the Linear release by hand (*If a Run Fails Part-Way*). +**A hotfix run is different: never rename the open release for it.** The open release holds +`main`'s unreleased pull requests; naming it after the hotfix would mark them shipped in the +hotfix. The Linear jobs check out the workflow's ref (`main`), not the **Branch** input, so they +never scan the hotfix branch: on a hotfix run `linear-sync` creates an empty `vX.Y.Z` release (or +none) and `linear-complete` completes it or fails, neither of which affects publishing. Attach +the hotfix's issues to that release by hand in Linear if it should list them. Syncing the hotfix +commits themselves would need the Linear jobs to check out the **Branch** input, a change to +`release.yml`. + Setup: the `LINEAR_ACCESS_KEY` repository secret, holding the access key of the pipeline meant for this repository's releases. From f9850d96fb27845f77950840c865a81b389f965e Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 00:14:57 -0800 Subject: [PATCH 3/8] docs(release): a hotfix Linear sync depends on the latest push sync (ITL-1193) Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 8b11631c8..3b44a4eab 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -363,10 +363,14 @@ by hand (*If a Run Fails Part-Way*). `main`'s unreleased pull requests; naming it after the hotfix would mark them shipped in the hotfix. The Linear jobs check out the workflow's ref (`main`), not the **Branch** input, so they never scan the hotfix branch: on a hotfix run `linear-sync` creates an empty `vX.Y.Z` release (or -none) and `linear-complete` completes it or fails, neither of which affects publishing. Attach -the hotfix's issues to that release by hand in Linear if it should list them. Syncing the hotfix -commits themselves would need the Linear jobs to check out the **Branch** input, a change to -`release.yml`. +none) and `linear-complete` completes it or fails, neither of which affects publishing. The +release is empty only if the latest push-to-`main` sync (`release-sync.yml`) succeeded: +`linear-sync` scans from the last synced commit, so after a failed or still-running push sync +it attaches those unsynced `main` commits to `vX.Y.Z` (no concurrency guard orders the two +workflows). Check that sync's latest run before a hotfix run; if it did not succeed, remove +those commits from `vX.Y.Z` by hand afterwards. Attach the hotfix's own issues to the release +by hand in Linear if it should list them. Syncing the hotfix commits themselves would need the +Linear jobs to check out the **Branch** input, a change to `release.yml`. Setup: the `LINEAR_ACCESS_KEY` repository secret, holding the access key of the pipeline meant for this repository's releases. From c833d988ad93139a8b5106cda43742824329ecd4 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 00:33:40 -0800 Subject: [PATCH 4/8] docs(release): inspect the Linear release after every hotfix run (ITL-1193) Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 3b44a4eab..2d7ca473b 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -362,15 +362,15 @@ by hand (*If a Run Fails Part-Way*). **A hotfix run is different: never rename the open release for it.** The open release holds `main`'s unreleased pull requests; naming it after the hotfix would mark them shipped in the hotfix. The Linear jobs check out the workflow's ref (`main`), not the **Branch** input, so they -never scan the hotfix branch: on a hotfix run `linear-sync` creates an empty `vX.Y.Z` release (or -none) and `linear-complete` completes it or fails, neither of which affects publishing. The -release is empty only if the latest push-to-`main` sync (`release-sync.yml`) succeeded: -`linear-sync` scans from the last synced commit, so after a failed or still-running push sync -it attaches those unsynced `main` commits to `vX.Y.Z` (no concurrency guard orders the two -workflows). Check that sync's latest run before a hotfix run; if it did not succeed, remove -those commits from `vX.Y.Z` by hand afterwards. Attach the hotfix's own issues to the release -by hand in Linear if it should list them. Syncing the hotfix commits themselves would need the -Linear jobs to check out the **Branch** input, a change to `release.yml`. +never scan the hotfix branch: `linear-sync` creates a `vX.Y.Z` release (or none) holding the +`main` commits that no push-to-`main` sync (`release-sync.yml`) has taken yet, usually none, and +`linear-complete` completes it or fails; neither affects publishing. No concurrency guard orders +the two workflows, so **after every hotfix run, inspect the `vX.Y.Z` Linear release** and, for +any `main` pull request it lists: move it and its issues to the open release by hand (the next +push sync starts after the commit the hotfix sync recorded, so it will not pick them up), and +put back the status of any of its issues that the completed release moved. Attach the hotfix's +own issues to `vX.Y.Z` by hand if it should list them. Syncing the hotfix commits themselves +would need the Linear jobs to check out the **Branch** input, a change to `release.yml`. Setup: the `LINEAR_ACCESS_KEY` repository secret, holding the access key of the pipeline meant for this repository's releases. From bf7700e7d3fb27337827db14ca59e55f8716c8e5 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 00:34:23 -0800 Subject: [PATCH 5/8] ci: read-only token in the test and release workflows; release-section bullet after ITL-1181 (ITL-1193) #417 (ITL-1181) has merged, so its files are free: run-tests.yml, run-postgres-tests.yml and release.yml get a top-level permissions: contents: read (the build and publish jobs keep their own grants), and the CLAUDE.md / .zed/rules bullet says lint.yml runs on every repository. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 5 +++++ .github/workflows/run-postgres-tests.yml | 4 ++++ .github/workflows/run-tests.yml | 4 ++++ .zed/rules | 6 ++++-- CLAUDE.md | 6 ++++-- 5 files changed, 21 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1ecf2598d..984902a57 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -20,6 +20,11 @@ on: type: boolean default: false +# Read-only token, whatever the repository default is (ITL-1193); the build +# and publish jobs grant themselves what they need. +permissions: + contents: read + jobs: validate-branch: name: Validate release branch diff --git a/.github/workflows/run-postgres-tests.yml b/.github/workflows/run-postgres-tests.yml index e1e068a8e..62b4326e0 100644 --- a/.github/workflows/run-postgres-tests.yml +++ b/.github/workflows/run-postgres-tests.yml @@ -6,6 +6,10 @@ on: pull_request: workflow_dispatch: # Allows manual triggering +# Read-only token, whatever the repository default is (ITL-1193). +permissions: + contents: read + jobs: test: runs-on: ubuntu-latest diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index d715b12ad..a9bbb2d78 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -6,6 +6,10 @@ on: pull_request: workflow_dispatch: # Allows manual triggering +# Read-only token, whatever the repository default is (ITL-1193). +permissions: + contents: read + jobs: test: needs: license-check diff --git a/.zed/rules b/.zed/rules index 58dfdd61a..94da15938 100644 --- a/.zed/rules +++ b/.zed/rules @@ -252,8 +252,10 @@ Developer decisions, November 16, 2026 (ITL-1193); the full procedure is RELEASI - An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, secret, environment, ruleset or the visibility of the repository. The v0.2.0 tag stays as it is. -- Linear, Codecov and SpiralDB jobs run only when - github.repository == 'metamorphic-labs/orcapod-python'; lint.yml runs on both repositories (ITL-1181). +- The jobs that use a secret (Linear, Codecov, SpiralDB) run only when + github.repository == 'metamorphic-labs/orcapod-python', so a fork's run skips them; + lint.yml runs on every repository (ITL-1181). Every workflow sets a read-only token + (permissions: contents: read); a job that needs more grants it to itself. ## Lint, format and type checks diff --git a/CLAUDE.md b/CLAUDE.md index 2133b93aa..75fae0f5d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -261,8 +261,10 @@ Developer decisions, November 16, 2026 (ITL-1193); the full procedure is `RELEAS - An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, secret, environment, ruleset or the visibility of the repository. The `v0.2.0` tag stays as it is. -- Linear, Codecov and SpiralDB jobs run only when - `github.repository == 'metamorphic-labs/orcapod-python'`; `lint.yml` runs on both repositories (ITL-1181). +- The jobs that use a secret (Linear, Codecov, SpiralDB) run only when + `github.repository == 'metamorphic-labs/orcapod-python'`, so a fork's run skips them; + `lint.yml` runs on every repository (ITL-1181). Every workflow sets a read-only token + (`permissions: contents: read`); a job that needs more grants it to itself. ## Lint, format and type checks From b20d950a478d23987f72ea8e89423f8299533ded Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 00:56:28 -0800 Subject: [PATCH 6/8] docs(release): describe the Linear scan range as the CLI computes it (ITL-1193) Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 2d7ca473b..940ac1f69 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -349,11 +349,12 @@ The workflow only syncs and completes the Linear release; any change of issue st comes with a completed release is made by Linear, as the workspace configures it. **Before the first run, and every run after it: name the open release.** Every push to `main` -adds its pull request to the open release, which has no version, and moves the scan start to -that commit. A release of `main`'s tip therefore finds no new commit: without a release named -`vX.Y.Z`, `linear-sync` creates an empty `vX.Y.Z` release (or none, if the CLI creates nothing -for an empty range), the open release holding the merged pull requests is left as it is, and -`linear-complete` completes the empty release or fails to find one. So, before running the +adds its pull request to the open release, which has no version, and records that commit. The +CLI scans from the commit recorded by the latest release reachable from `HEAD`, exclusive +(`..HEAD`), and creates no release for an empty range. A release of `main`'s tip +therefore finds no new commit: without a release named `vX.Y.Z`, `linear-sync` creates nothing, +the open release holding the merged pull requests is left as it is, and `linear-complete` fails +to find `vX.Y.Z`. So, before running the Release workflow, the developer sets the version of the pipeline's open release to `vX.Y.Z` in Linear (pre-release checklist, item 6); `linear-sync` then targets it and `linear-complete` completes it. If a Linear job fails anyway, the release is published; finish the Linear release @@ -362,14 +363,16 @@ by hand (*If a Run Fails Part-Way*). **A hotfix run is different: never rename the open release for it.** The open release holds `main`'s unreleased pull requests; naming it after the hotfix would mark them shipped in the hotfix. The Linear jobs check out the workflow's ref (`main`), not the **Branch** input, so they -never scan the hotfix branch: `linear-sync` creates a `vX.Y.Z` release (or none) holding the -`main` commits that no push-to-`main` sync (`release-sync.yml`) has taken yet, usually none, and -`linear-complete` completes it or fails; neither affects publishing. No concurrency guard orders -the two workflows, so **after every hotfix run, inspect the `vX.Y.Z` Linear release** and, for -any `main` pull request it lists: move it and its issues to the open release by hand (the next -push sync starts after the commit the hotfix sync recorded, so it will not pick them up), and -put back the status of any of its issues that the completed release moved. Attach the hotfix's -own issues to `vX.Y.Z` by hand if it should list them. Syncing the hotfix commits themselves +never scan the hotfix branch. When the push-to-`main` sync (`release-sync.yml`) has recorded +`main`'s tip, the range is empty: `linear-sync` creates nothing and `linear-complete` fails, which +does not affect publishing. When it has not (it failed, or is still running), `linear-sync` +creates `vX.Y.Z` holding those unsynced `main` commits and `linear-complete` completes it. No +concurrency guard orders the two workflows, so **after every hotfix run, check Linear for a +`vX.Y.Z` release**. If there is one, for any `main` pull request it lists: move it and its issues +to the open release by hand (the next push sync starts after the commit the hotfix sync +recorded, so it will not pick them up), and put back the status of any of its issues that the +completed release moved. Create or edit `vX.Y.Z` by hand if it should list the hotfix's own +issues. Syncing the hotfix commits themselves would need the Linear jobs to check out the **Branch** input, a change to `release.yml`. Setup: the `LINEAR_ACCESS_KEY` repository secret, holding the access key of the pipeline meant From 590b0d374552c2d7c8692d520ea2f9d380b87ca2 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 01:19:27 -0800 Subject: [PATCH 7/8] docs(release): no merges into main from the Linear rename to its completion; hotfix cleanup covers issues (ITL-1193) Co-Authored-By: Claude Opus 5.5 --- RELEASING.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 940ac1f69..d9f2a2eef 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -103,8 +103,8 @@ All of these hold before the developer runs the Release workflow: 5. **The version is free**: the tag does not exist on `metamorphic-labs`, and the version is on neither PyPI nor TestPyPI. 6. **The Linear release is named** (see *Linear Release System*): the open release of the - Linear release pipeline has the version `vX.Y.Z`. Not for a hotfix run, which leaves the open - release as it is. + Linear release pipeline has the version `vX.Y.Z`, and nothing merges into `main` until + `linear-complete` has finished. Not for a hotfix run, which leaves the open release as it is. ## Golden hash values @@ -357,7 +357,11 @@ the open release holding the merged pull requests is left as it is, and `linear- to find `vX.Y.Z`. So, before running the Release workflow, the developer sets the version of the pipeline's open release to `vX.Y.Z` in Linear (pre-release checklist, item 6); `linear-sync` then targets it and `linear-complete` -completes it. If a Linear job fails anyway, the release is published; finish the Linear release +completes it. From the rename until `linear-complete` has finished, merge nothing into `main`: +a push sync in between adds its pull request to the renamed release, which would mark it +shipped in `vX.Y.Z` although the build does not contain it. If one slips in, move it and its +issues back to the next open release by hand, and put back the status of any issue the +completed release moved. If a Linear job fails anyway, the release is published; finish the Linear release by hand (*If a Run Fails Part-Way*). **A hotfix run is different: never rename the open release for it.** The open release holds @@ -368,10 +372,11 @@ never scan the hotfix branch. When the push-to-`main` sync (`release-sync.yml`) does not affect publishing. When it has not (it failed, or is still running), `linear-sync` creates `vX.Y.Z` holding those unsynced `main` commits and `linear-complete` completes it. No concurrency guard orders the two workflows, so **after every hotfix run, check Linear for a -`vX.Y.Z` release**. If there is one, for any `main` pull request it lists: move it and its issues -to the open release by hand (the next push sync starts after the commit the hotfix sync -recorded, so it will not pick them up), and put back the status of any of its issues that the -completed release moved. Create or edit `vX.Y.Z` by hand if it should list the hotfix's own +`vX.Y.Z` release**. If there is one, for every `main` pull request and every issue it lists (the +CLI picks up issue ids from commit messages as well as pull requests, so an issue can be listed +without its pull request): move it to the open release by hand (the next push sync starts +after the commit the hotfix sync recorded, so it will not pick them up), and put back the +status of any issue that the completed release moved. Create or edit `vX.Y.Z` by hand if it should list the hotfix's own issues. Syncing the hotfix commits themselves would need the Linear jobs to check out the **Branch** input, a change to `release.yml`. From be2e454dcacc9a43d2f0b9af52e5385b46bda9a8 Mon Sep 17 00:00:00 2001 From: "Edgar Y. Walker" <> Date: Tue, 17 Nov 2026 01:50:10 -0800 Subject: [PATCH 8/8] ci(codecov): upload by GitHub OIDC and post statuses after all uploads (ITL-1193) - run-tests.yml, run-postgres-tests.yml, run-objective-tests.yml: the coverage jobs grant themselves id-token: write and upload with use_oidc: true instead of the CODECOV_TOKEN organization secret, which is shared with private repositories only and vanishes at the public flip. A fork's pull request uploads tokenless. fail_ci_if_error is on except on pull requests. - codecov.yml: codecov.notify.after_n_builds: 7. Codecov posted its statuses after the first uploads (Objective, PostgreSQL: about 25% each), so PRs showed red until Run Tests' upload was processed. - RELEASING.md: Coverage uploads; round-6 review wording (a slipped merge the build contains stays; a failed Linear job: check publish-pypi first). - CLAUDE.md, .zed/rules, AGENT_COORDINATION.md: Linear linkbacks stay enabled, so nothing private goes into a Linear issue an Orcapod PR links. - README, docs/concepts/arrays.md, docs/reference/hashing.md, CLAUDE.md: library value types are provisional until the library value type audit, after 0.4.0rc1. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/run-objective-tests.yml | 11 ++++++- .github/workflows/run-postgres-tests.yml | 11 ++++++- .github/workflows/run-tests.yml | 11 ++++++- .zed/rules | 16 ++++++---- AGENT_COORDINATION.md | 5 +++- CLAUDE.md | 16 ++++++---- README.md | 5 ++-- RELEASING.md | 36 +++++++++++++++++++---- changelog.d/ITL-1193.md | 3 ++ codecov.yml | 11 +++++++ docs/concepts/arrays.md | 12 ++++---- docs/reference/hashing.md | 3 +- 12 files changed, 112 insertions(+), 28 deletions(-) diff --git a/.github/workflows/run-objective-tests.yml b/.github/workflows/run-objective-tests.yml index 0a031c359..3a25980f6 100644 --- a/.github/workflows/run-objective-tests.yml +++ b/.github/workflows/run-objective-tests.yml @@ -13,6 +13,12 @@ permissions: jobs: test: runs-on: ubuntu-latest + # id-token: write lets the Codecov upload authenticate by GitHub OIDC, with no stored + # token (ITL-1193). A fork's pull request gets no OIDC token: the action detects the fork + # and uploads tokenless instead. + permissions: + contents: read + id-token: write strategy: matrix: python-version: ["3.11", "3.12", "3.13"] @@ -41,4 +47,7 @@ jobs: if: github.repository == 'metamorphic-labs/orcapod-python' uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0 with: - token: ${{ secrets.CODECOV_TOKEN }} + use_oidc: true + # A failed upload fails a push run, where it would otherwise go unseen; it never + # fails a pull request, whose fork uploads are tokenless (ITL-1193). + fail_ci_if_error: ${{ github.event_name != 'pull_request' }} diff --git a/.github/workflows/run-postgres-tests.yml b/.github/workflows/run-postgres-tests.yml index 62b4326e0..75a28f078 100644 --- a/.github/workflows/run-postgres-tests.yml +++ b/.github/workflows/run-postgres-tests.yml @@ -13,6 +13,12 @@ permissions: jobs: test: runs-on: ubuntu-latest + # id-token: write lets the Codecov upload authenticate by GitHub OIDC, with no stored + # token (ITL-1193). A fork's pull request gets no OIDC token: the action detects the fork + # and uploads tokenless instead. + permissions: + contents: read + id-token: write strategy: matrix: python-version: ["3.11", "3.12", "3.13"] @@ -63,4 +69,7 @@ jobs: if: github.repository == 'metamorphic-labs/orcapod-python' uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0 with: - token: ${{ secrets.CODECOV_TOKEN }} + use_oidc: true + # A failed upload fails a push run, where it would otherwise go unseen; it never + # fails a pull request, whose fork uploads are tokenless (ITL-1193). + fail_ci_if_error: ${{ github.event_name != 'pull_request' }} diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index a9bbb2d78..51ad9e7a0 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -14,6 +14,12 @@ jobs: test: needs: license-check runs-on: ubuntu-latest + # id-token: write lets the Codecov upload authenticate by GitHub OIDC, with no stored + # token (ITL-1193). A fork's pull request gets no OIDC token: the action detects the fork + # and uploads tokenless instead. + permissions: + contents: read + id-token: write strategy: # A pull request runs one job, on Python 3.13, whose coverage is the one reported; a # push (main) runs all three versions (developer, November 16, 2026; ITL-1181). A @@ -58,7 +64,10 @@ jobs: if: github.repository == 'metamorphic-labs/orcapod-python' uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0 with: - token: ${{ secrets.CODECOV_TOKEN }} + use_oidc: true + # A failed upload fails a push run, where it would otherwise go unseen; it never + # fails a pull request, whose fork uploads are tokenless (ITL-1193). + fail_ci_if_error: ${{ github.event_name != 'pull_request' }} spiral-integration: runs-on: ubuntu-latest diff --git a/.zed/rules b/.zed/rules index 94da15938..55b1d0748 100644 --- a/.zed/rules +++ b/.zed/rules @@ -249,11 +249,16 @@ Developer decisions, November 16, 2026 (ITL-1193); the full procedure is RELEASI private repository, no credential or secret value, no Linear text that is not about this repository, and nothing about the full EDI dataset (its location, storage, projects or tables). +- Linear's linkback comments stay enabled (developer, November 16, 2026): every PR that links a + Linear issue gets a comment holding that issue's text, in public. So nothing about the full + EDI dataset or internal infrastructure is written into a Linear issue that an Orcapod PR + links; put such material in an issue no PR links. - An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, secret, environment, ruleset or the visibility of the repository. The v0.2.0 tag stays as it is. -- The jobs that use a secret (Linear, Codecov, SpiralDB) run only when - github.repository == 'metamorphic-labs/orcapod-python', so a fork's run skips them; +- The Linear, Codecov and SpiralDB jobs run only when + github.repository == 'metamorphic-labs/orcapod-python', so a fork's push run skips them + (Codecov uploads by GitHub OIDC, with no stored token; RELEASING.md, *Coverage uploads*); lint.yml runs on every repository (ITL-1181). Every workflow sets a read-only token (permissions: contents: read); a job that needs more grants it to itself. @@ -386,9 +391,10 @@ Developer, November 12, 2026 (ITL-981); see `docs/concepts/arrays.md` and `allow_pickle=False` on write and read; never raise `max_header_size`). Options: `memory_order`, `byte_order`, `struct_layout`. Where stored arrays must be ordered, order them by value hash (`storage_sort_key`), never by stored bytes. -- Library value types are provisional until the v0.4 audit (developer, November 13, 2026, - ITL-1068): their extension names are listed in `provisional` of - `contexts/logical_types.json`, and using one issues `ProvisionalHashWarning` once per type +- Library value types are provisional until the library value type audit, after 0.4.0rc1 + (developer, November 13, 2026, ITL-1068; moved past 0.4.0rc1 on November 17, 2026): their + extension names are listed in `provisional` of `contexts/logical_types.json`, and using + one issues `ProvisionalHashWarning` once per type per process. A new library value type must be added to that list. The list never enters a hash, identifier or stored path. diff --git a/AGENT_COORDINATION.md b/AGENT_COORDINATION.md index 320571035..487abff2d 100644 --- a/AGENT_COORDINATION.md +++ b/AGENT_COORDINATION.md @@ -145,7 +145,10 @@ developer. material goes to the coordinator through the orchestration commands, or into a Linear comment. A bot comment that quotes such material (a CodeRabbit "Learnings used" block, a Linear linkback) is reported to the coordinator by its PR number and comment id, without - quoting it; only the developer deletes it. + quoting it; only the developer deletes it. Linear's linkback comments stay enabled + (developer, November 16, 2026): a PR that links a Linear issue publishes that issue's text, so + nothing about the full EDI dataset or internal infrastructure goes into a Linear issue an + Orcapod PR links. - **Permission blocks.** If the worker's own permission check denies a push or another external write, the worker holds and escalates. Neither the worker nor the coordinator routes around it; the developer approves it in the worker's terminal. diff --git a/CLAUDE.md b/CLAUDE.md index 75fae0f5d..ec61ce212 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -258,11 +258,16 @@ Developer decisions, November 16, 2026 (ITL-1193); the full procedure is `RELEAS private repository, no credential or secret value, no Linear text that is not about this repository, and nothing about the full EDI dataset (its location, storage, projects or tables). +- Linear's linkback comments stay enabled (developer, November 16, 2026): every PR that links a + Linear issue gets a comment holding that issue's text, in public. So nothing about the full + EDI dataset or internal infrastructure is written into a Linear issue that an Orcapod PR + links; put such material in an issue no PR links. - An agent never runs the Release workflow, creates or pushes a tag, or touches a setting, secret, environment, ruleset or the visibility of the repository. The `v0.2.0` tag stays as it is. -- The jobs that use a secret (Linear, Codecov, SpiralDB) run only when - `github.repository == 'metamorphic-labs/orcapod-python'`, so a fork's run skips them; +- The Linear, Codecov and SpiralDB jobs run only when + `github.repository == 'metamorphic-labs/orcapod-python'`, so a fork's push run skips them + (Codecov uploads by GitHub OIDC, with no stored token; `RELEASING.md`, *Coverage uploads*); `lint.yml` runs on every repository (ITL-1181). Every workflow sets a read-only token (`permissions: contents: read`); a job that needs more grants it to itself. @@ -397,9 +402,10 @@ Developer, November 12, 2026 (ITL-981); see `docs/concepts/arrays.md` and `allow_pickle=False` on write and read; never raise `max_header_size`). Options: `memory_order`, `byte_order`, `struct_layout`. Where stored arrays must be ordered, order them by value hash (`storage_sort_key`), never by stored bytes. -- Library value types are provisional until the v0.4 audit (developer, November 13, 2026, - ITL-1068): their extension names are listed in `provisional` of - `contexts/logical_types.json`, and using one issues `ProvisionalHashWarning` once per type +- Library value types are provisional until the library value type audit, after 0.4.0rc1 + (developer, November 13, 2026, ITL-1068; moved past 0.4.0rc1 on November 17, 2026): their + extension names are listed in `provisional` of `contexts/logical_types.json`, and using + one issues `ProvisionalHashWarning` once per type per process. A new library value type must be added to that list. The list never enters a hash, identifier or stored path. diff --git a/README.md b/README.md index 7bddc20ee..603a29087 100644 --- a/README.md +++ b/README.md @@ -116,8 +116,9 @@ Orcapod is before version 1.0. In 0.3.0: same data context; CI checks this. 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 may change in 0.4, and results computed - from them may then be computed again. Using one issues `ProvisionalHashWarning` once per + pandas and polars `DataFrame` and `Series` values are provisional until the library value + type audit (after 0.4.0rc1) and may change then; results computed from them may then be + 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 diff --git a/RELEASING.md b/RELEASING.md index d9f2a2eef..5c46d9975 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -215,13 +215,38 @@ secrets or environments: `refs/tags/v*`; deletion, update, non-fast-forward; no bypass actors), so the golden tag check has a fixed anchor (ITL-946). Done on 2026-11-15. 5. The `LINEAR_ACCESS_KEY` repository secret, for the Linear jobs (see *Linear Release - System*), and the organization secret `CODECOV_TOKEN`, for the coverage uploads. + 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. +### Coverage uploads + +The coverage jobs of `Run Tests`, `Run PostgreSQL Tests` and `Run Objective Tests` upload to +Codecov without a stored token (ITL-1193). The organization secret `CODECOV_TOKEN` is shared +with private and internal repositories only, so it would vanish when this repository became +public, and a token upload would then fail silently. + +- **Pushes, `workflow_dispatch` and pull requests from a branch of this repository** + authenticate by GitHub OIDC: the job grants itself `id-token: write`, and the action + (`use_oidc: true`) sends a short-lived token signed by GitHub, which Codecov checks against + GitHub's public keys. Nothing is stored here or set up in Codecov. +- **Pull requests from a fork** get no OIDC token. The action detects the fork and uploads + without a token, under a `:` branch name, which Codecov accepts for a public + repository. +- `fail_ci_if_error` is on for every run except a pull request: a failed upload of `main` is + seen, and a fork's tokenless upload can never fail its pull request. +- `codecov.yml` holds Codecov's statuses until 7 uploads are in (`codecov.notify.after_n_builds`), + so a pull request's statuses wait for the main test job's coverage. The comment there + explains the number; change it with any change to the three workflows' matrices. + +The developer keeps Codecov's organization setting *token required for public repositories* +at **Required**: then only OIDC (or a token) can upload to `main`, and only a fork's branch name +uploads tokenless. Turning it off would let anyone upload to any branch of every public +repository of the organization. + ### SpiralDB integration job The `spiral-integration` job of `Run Tests` runs on every push to `main` and by hand @@ -359,10 +384,11 @@ Release workflow, the developer sets the version of the pipeline's open release Linear (pre-release checklist, item 6); `linear-sync` then targets it and `linear-complete` completes it. From the rename until `linear-complete` has finished, merge nothing into `main`: a push sync in between adds its pull request to the renamed release, which would mark it -shipped in `vX.Y.Z` although the build does not contain it. If one slips in, move it and its -issues back to the next open release by hand, and put back the status of any issue the -completed release moved. If a Linear job fails anyway, the release is published; finish the Linear release -by hand (*If a Run Fails Part-Way*). +shipped in `vX.Y.Z` although the build does not contain it. If one slips in, check whether the +build contains it (`git merge-base --is-ancestor vX.Y.Z`): if it does, it stays in +`vX.Y.Z`; if not, move it and its issues back to the next open release by hand, and put back the +status of any issue the completed release moved. If a Linear job fails anyway, check `publish-pypi` first: if it succeeded, finish +the Linear release by hand; if not, recover publishing first (*If a Run Fails Part-Way*). **A hotfix run is different: never rename the open release for it.** The open release holds `main`'s unreleased pull requests; naming it after the hotfix would mark them shipped in the diff --git a/changelog.d/ITL-1193.md b/changelog.d/ITL-1193.md index ae924d42b..f4c33d817 100644 --- a/changelog.d/ITL-1193.md +++ b/changelog.d/ITL-1193.md @@ -4,3 +4,6 @@ The package's project URLs (homepage, repository, changelog, issues), the links in `README.md` and the tutorial's install and download commands point to it. `nauticalab/orcapod-python`, the release repository up to 0.3.0, is being retired. (ITL-1193) +- The library value types (`numpy.ndarray`, `torch.Tensor`, pandas and polars `DataFrame` + and `Series`) stay provisional until the library value type audit, which comes after + 0.4.0rc1 rather than with 0.4; the documentation says so. (ITL-1193) diff --git a/codecov.yml b/codecov.yml index c7916c552..0bedc3ec1 100644 --- a/codecov.yml +++ b/codecov.yml @@ -1,3 +1,14 @@ +codecov: + notify: + # Post the project and patch statuses only once the uploads that carry the main test + # coverage are in (ITL-1193). A pull request uploads 7 reports (Run Tests on Python 3.13, + # Run Objective Tests and Run PostgreSQL Tests on 3.11, 3.12 and 3.13); a push uploads 9 + # (Run Tests on all three). The objective and PostgreSQL uploads come first and cover + # about a quarter of the code each, so without this the statuses went red until Run Tests' + # upload was processed. 7 is every upload of a pull request, and on a push the seventh + # upload is always a Run Tests one. Change this number with any change to those matrices. + after_n_builds: 7 + ignore: - "src/orcapod/protocols/**" diff --git a/docs/concepts/arrays.md b/docs/concepts/arrays.md index 5fdb40bb3..7332f0b41 100644 --- a/docs/concepts/arrays.md +++ b/docs/concepts/arrays.md @@ -45,8 +45,8 @@ for tag, data in scale.pod(source).iter_data(): ## Provisional value hashes The value hashes and stored identities of the library value types are provisional in v0.3: -`numpy.ndarray`, `torch.Tensor`, and the pandas and polars `DataFrame` and `Series`. They -will be reviewed for v0.4 and may change then. Every other type, and the hashing of everything +`numpy.ndarray`, `torch.Tensor`, and the pandas and polars `DataFrame` and `Series`. They are +provisional until the library value type audit (after 0.4.0rc1) and may change then. Every other type, and the hashing of everything else in a pipeline, is unaffected. Using one of these types issues `orcapod.errors.ProvisionalHashWarning` once per type per @@ -54,10 +54,10 @@ process, on whichever use comes first: a value hashed, a source column of the ty pod with a parameter or output of the type, or stored results of the type read back. It names the type, for example `orcapod.numpy.ndarray`. -In practice nothing needs to change. Use these types as described on this page. If v0.4 -changes how one of them is hashed, a result Orcapod computed under v0.3 from such a value gets -a different identity, so v0.4 computes it again instead of reusing it. Nothing stored is lost -or becomes wrong: the v0.3 rows stay where they are. Plan for that recomputation if a +In practice nothing needs to change. Use these types as described on this page. If the audit +changes how one of them is hashed, a result Orcapod computed earlier from such a value gets a +different identity, so the release that carries the change computes it again instead of reusing +it. Nothing stored is lost or becomes wrong: the earlier rows stay where they are. Plan for that recomputation if a pipeline is expensive. To silence the warning once you have taken note of it, filter its class after importing Orcapod: diff --git a/docs/reference/hashing.md b/docs/reference/hashing.md index 29c65ba3d..51d02b53e 100644 --- a/docs/reference/hashing.md +++ b/docs/reference/hashing.md @@ -1172,7 +1172,8 @@ in any data-level preimage; they serve logging, observability, and result inspec **Provisional.** The value hashes of the library value types, `numpy.ndarray` (this section), `torch.Tensor` ([below](#torch-tensor-value-hash)), polars `DataFrame` and `Series` ([1e](#1e-polars-dataframe-and-series-values)) and pandas `DataFrame` and `Series`, and their -logical type identifiers, are provisional in v0.3 and may change in v0.4. Using one issues +logical type identifiers, are provisional until the library value type audit (after +0.4.0rc1) and may change then. Using one issues `ProvisionalHashWarning` once per type per process (see [Provisional value hashes](../concepts/arrays.md#provisional-value-hashes)). The types are declared in the `provisional` list of `orcapod/contexts/logical_types.json`, by extension name;