rosotacom-dev 2.2__tar.gz → 2.4__tar.gz

rosotacom_dev-2.4/.github/workflows/dev-release.yml

@@ -0,0 +1,152 @@
+name: Dev release
+
+# Every commit that lands on develop becomes an installable pre-release.
+#
+# Consuming this package should not mean consuming something days old. Without
+# this, a downstream repository could only pin a version after someone decided
+# to cut a release, so "always consume the package, never the checkout" cost a
+# human decision per iteration — and the cheap way out was to stop consuming the
+# package.
+#
+# setuptools-scm already derives X.Y.devN from the history; those wheels were
+# built by CI and thrown away. This publishes them.
+#
+# `pip` does not resolve pre-releases unless asked, so the stable line is
+# unaffected: nobody gets a dev version by accident, and anybody who wants one
+# pins it exactly. Cutting a stable vX.Y stays a deliberate, human decision in
+# release.yml.
+#
+# It runs on workflow_run rather than on push, so a commit whose CI failed is
+# never published. workflow_run resolves this file from the default branch,
+# which is develop — the branch it watches.
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [develop]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: publish
+    runs-on: ubuntu-latest
+    # `event == 'push'` keeps pull-request CI runs out: only what actually
+    # landed on develop is published.
+    if: >-
+      github.event.workflow_run.conclusion == 'success'
+      && github.event.workflow_run.event == 'push'
+    # Same authorization as release.yml: the per-repo Trusted Publisher,
+    # registered with a blank environment. No token, no environment admin.
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Check out the commit CI validated
+        uses: actions/checkout@v6
+        with:
+          # Pin to the validated commit: develop may have moved on since, and
+          # publishing a different tree than the one that passed would make the
+          # version meaningless.
+          ref: ${{ github.event.workflow_run.head_sha }}
+          # setuptools-scm needs the full history and the tags to derive the
+          # version; a shallow clone silently yields 0.1.dev1.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install just
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y just
+
+      - name: Set up local environment
+        run: just setup
+
+      - name: Build and validate distributions
+        run: just package
+
+      - name: Require a pre-release version
+        id: version
+        run: |
+          set -euo pipefail
+          # A wheel filename is name-version-pytag-abitag-plattag.whl.
+          shopt -s nullglob
+          wheels=(dist/*.whl)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "::error::expected exactly one wheel in dist/, found ${#wheels[@]}"
+            exit 1
+          fi
+          base="$(basename "${wheels[0]}" .whl)"
+          name="${base%%-*}"
+          rest="${base#*-}"
+          version="${rest%%-*}"
+          echo "distribution=${name//_/-}" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Built ${name//_/-} $version"
+          # A clean X.Y here means develop points at a tagged commit. That
+          # version belongs to the stable line and release.yml owns it, so skip
+          # rather than race it onto the index under a second identity.
+          if [ "${version#*.dev}" = "$version" ]; then
+            echo "::notice::$version is not a pre-release; the stable tag path owns it. Skipping."
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Remove checksum sidecar
+        if: steps.version.outputs.publish == 'true'
+        run: rm -f dist/SHA256SUMS
+
+      - name: Verify configured publishing target
+        if: steps.version.outputs.publish == 'true'
+        env:
+          PYPI_PUBLISH_URL: ${{ vars.PYPI_PUBLISH_URL }}
+        run: |
+          if [ -z "$PYPI_PUBLISH_URL" ]; then
+            echo "::error::PYPI_PUBLISH_URL is not configured for this repository."
+            exit 1
+          fi
+          case "$PYPI_PUBLISH_URL" in
+            https://*) ;;
+            *)
+              echo "::error::PYPI_PUBLISH_URL must be an HTTPS endpoint (offending value: '$PYPI_PUBLISH_URL')."
+              exit 1
+              ;;
+          esac
+
+      # No TestPyPI rehearsal here. The dev channel *is* the rehearsal, and a
+      # second upload per commit would double the noise for no extra signal.
+      - name: Publish pre-release
+        if: steps.version.outputs.publish == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ vars.PYPI_PUBLISH_URL }}
+          skip-existing: true
+
+      - name: Summarise
+        if: steps.version.outputs.publish == 'true'
+        env:
+          DISTRIBUTION: ${{ steps.version.outputs.distribution }}
+          VERSION: ${{ steps.version.outputs.version }}
+          COMMIT: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          # Markdown code block by indentation: no backticks, which shellcheck
+          # would read as command substitution.
+          {
+            echo "Published $VERSION from $COMMIT."
+            echo
+            echo "Consume it with:"
+            echo
+            echo "    pipx install \"$DISTRIBUTION==$VERSION\""
+          } >> "$GITHUB_STEP_SUMMARY"

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/.github/workflows/release.yml

@@ -77,6 +77,29 @@ jobs:
       - name: Build and validate distributions
         run: just package
 
+      # The mirror of the dev channel's guard. A tag build must produce the
+      # clean version the tag names; a pre-release here means the tag is not on
+      # the commit being built (a dirty tree, or a tag pushed from the wrong
+      # place), and the release would silently publish something else.
+      - name: Require a stable version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          wheels=(dist/*.whl)
+          if [ "${#wheels[@]}" -ne 1 ]; then
+            echo "::error::expected exactly one wheel in dist/, found ${#wheels[@]}"
+            exit 1
+          fi
+          base="$(basename "${wheels[0]}" .whl)"
+          rest="${base#*-}"
+          version="${rest%%-*}"
+          expected="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$expected" ]; then
+            echo "::error::tag $GITHUB_REF_NAME builds version $version, not $expected."
+            exit 1
+          fi
+
       - name: Generate checksums
         run: |
           cd dist

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/AGENTS.md

@@ -43,6 +43,21 @@ Shared workflow:
   is unavailable, record why in the PR and final status.
 - Keep the PR description current with the issue link, validation commands,
   important SHAs, CI status, and any dependency on another PR or harness MR.
+
+Release autonomy — where the human decision actually is:
+
+- Agents run a change to the end: branch, PR, CI, auto-merge. Merging publishes
+  a `X.Y.devN` pre-release automatically (`.github/workflows/dev-release.yml`),
+  so a downstream repository can pin the result immediately. Nothing about that
+  needs a human, and a merged change that nobody can consume is not finished.
+- Cutting a stable `vX.Y.Z` tag is the one release step that is a decision, not
+  a consequence: the version is a promise to consumers and cannot be taken back
+  once it is on the index. Cut one only when the task says so.
+- A stable tag needs `docs/release-notes/vX.Y.Z.md` **in the tagged commit**.
+  Add it in the PR that will be tagged; adding it afterwards leaves the release
+  job failing on a tag that cannot be moved.
+- Never reuse or move a published version. If a release is wrong, supersede it
+  with the next one and say so in its notes.
 - Before reporting completion, check the remote PR state and CI results with
   `gh pr view` / `gh pr checks`; report the actual status, not just that a
   branch was pushed.

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/CONTRIBUTING.md

@@ -112,17 +112,30 @@ repository settings that live outside git.
 
 ## Release Workflow
 
-Releases are built from tags in the form `vX.Y.Z`. Release PRs must include
-`docs/release-notes/vX.Y.Z.md`, copied from
-[docs/release-notes/TEMPLATE.md](docs/release-notes/TEMPLATE.md).
+Two channels, described in full in [docs/release.md](docs/release.md).
 
-After the release PR has merged to `main`, verify the exact commit and then:
+**Development channel.** Every commit that lands on the development branch with
+green CI is published automatically as `X.Y.devN`. There is nothing to do and
+nothing to decide: merging *is* releasing on this channel. Consume such a
+version with an exact pin, which is how a downstream repository tracks work in
+progress without reaching past the package boundary:
 
 ```bash
-git switch main
+pipx install "rosotacom-dev==2.4.dev3"
+```
+
+**Stable release.** Built from tags in the form `vX.Y.Z`. Release PRs must
+include `docs/release-notes/vX.Y.Z.md`, copied from
+[docs/release-notes/TEMPLATE.md](docs/release-notes/TEMPLATE.md) — the tagged
+commit has to contain its own notes, so the notes land in the PR, not after it.
+
+After the release PR has merged, verify the exact commit and then:
+
+```bash
+git switch develop
 git fetch --prune
 git pull --ff-only
-git tag vX.Y.Z
+git tag -a vX.Y.Z -m "rosotacom vX.Y.Z"
 git push origin vX.Y.Z
 ```
 

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.2
+Version: 2.4
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -98,6 +98,9 @@ pipx install rosotacom-dev        # isolated, on PATH everywhere
      on PyPI stays reserved for the FZI upstream. -->
 #   or: pip install --user rosotacom
 
+# a specific development build (for consumers tracking work in progress)
+pipx install "rosotacom-dev==2.4.dev3"
+
 # from a source checkout (developers)
 cd /path/to/ros_communication_devcontainer
 ./install.sh                      # builds a checkout-local .venv
@@ -109,6 +112,12 @@ python -m rosotacom --version
 rosotacom doctor
 ```
 
+Every commit that lands on the development branch with green CI is published as
+a `X.Y.devN` pre-release, so a consumer never has to wait for a release decision
+or reach past the package to a checkout. `pip` ignores pre-releases unless you
+pin one exactly, so this cannot reach you by accident. See
+[docs/release.md](docs/release.md).
+
 For a source checkout, that single `source .venv/bin/activate` command also
 enables completion. Nothing needs to be added to your shell configuration.
 
@@ -218,6 +227,23 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+### Locating packaged resources
+
+rosotacom is installed in an isolated environment (pipx, or a project venv), so
+another tool cannot `import rosotacom` from a system Python to find the files
+that ship with it. Ask the CLI instead — it prints one absolute path, so it
+composes directly in a shell:
+
+```bash
+rosotacom resources path com_msgs   # the ROS 2 message package
+rosotacom resources path ws         # the packaged runtime workspace
+```
+
+Use this wherever another project needs rosotacom's files on the host, for
+example to bake `com_msgs` into its own container image. Ask for the resource by
+name rather than reconstructing a path: the names are part of the CLI contract,
+the layout behind them is not.
+
 See the [example project README](src/rosotacom/resources/examples/README.md)
 for the copyable example layout, the
 [session configuration reference](session-configuration.md) for the session
@@ -411,10 +437,10 @@ rosotacom ota-smoke 2_native_chatter \
   --peer b=robot
 ```
 
-`ota-smoke` accepts sessions and scenarios. It automatically stages and
-installs the currently selected rosotacom version, stages the active project,
-runs delivery and isolation checks, collects artifacts, stops the run, and
-removes the remote workdir. Add `--interactive` for a local control tmux with
+`ota-smoke` accepts sessions and scenarios. It puts rosotacom on each peer,
+stages the active project, runs delivery and isolation checks, collects
+artifacts, stops the run, and removes the remote workdir. Add `--interactive`
+for a local control tmux with
 one attachable communication/catmux window per peer with a live status pane below
 each one. Scenario targets also get one native application-container window per
 scenario app. Stop an interactive run with `rosotacom ota-smoke TARGET
@@ -423,6 +449,29 @@ metadata is not available. Use `--keep-running` to leave components up,
 `--keep-workdir` to retain staged files, or `--reuse` to reuse an existing
 installation.
 
+#### What the peers run: `--install-mode`
+
+```bash
+# default: stage and install what you are running, uncommitted changes included
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot
+
+# rehearse a deployment: the peers install the published artefact
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode pin                # defaults to your own version
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode pin --install-pin 2.4
+```
+
+`source` is right while iterating on rosotacom itself — the peers run the code
+in front of you. `pin` is right when the run is meant to stand in for a real
+deployment: the peers install from the index, so a packaging defect (a file
+missing from the wheel, an undeclared dependency) fails in the rehearsal instead
+of on the target machine. `source` cannot catch that class of defect by
+construction, because it never builds the artefact that ships.
+
+The run manifest records which mode and which version the peers ran, so a result
+can be attributed to an artefact rather than to a working copy.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/README.md

@@ -53,6 +53,9 @@ pipx install rosotacom-dev        # isolated, on PATH everywhere
      on PyPI stays reserved for the FZI upstream. -->
 #   or: pip install --user rosotacom
 
+# a specific development build (for consumers tracking work in progress)
+pipx install "rosotacom-dev==2.4.dev3"
+
 # from a source checkout (developers)
 cd /path/to/ros_communication_devcontainer
 ./install.sh                      # builds a checkout-local .venv
@@ -64,6 +67,12 @@ python -m rosotacom --version
 rosotacom doctor
 ```
 
+Every commit that lands on the development branch with green CI is published as
+a `X.Y.devN` pre-release, so a consumer never has to wait for a release decision
+or reach past the package to a checkout. `pip` ignores pre-releases unless you
+pin one exactly, so this cannot reach you by accident. See
+[docs/release.md](docs/release.md).
+
 For a source checkout, that single `source .venv/bin/activate` command also
 enables completion. Nothing needs to be added to your shell configuration.
 
@@ -173,6 +182,23 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+### Locating packaged resources
+
+rosotacom is installed in an isolated environment (pipx, or a project venv), so
+another tool cannot `import rosotacom` from a system Python to find the files
+that ship with it. Ask the CLI instead — it prints one absolute path, so it
+composes directly in a shell:
+
+```bash
+rosotacom resources path com_msgs   # the ROS 2 message package
+rosotacom resources path ws         # the packaged runtime workspace
+```
+
+Use this wherever another project needs rosotacom's files on the host, for
+example to bake `com_msgs` into its own container image. Ask for the resource by
+name rather than reconstructing a path: the names are part of the CLI contract,
+the layout behind them is not.
+
 See the [example project README](src/rosotacom/resources/examples/README.md)
 for the copyable example layout, the
 [session configuration reference](session-configuration.md) for the session
@@ -366,10 +392,10 @@ rosotacom ota-smoke 2_native_chatter \
   --peer b=robot
 ```
 
-`ota-smoke` accepts sessions and scenarios. It automatically stages and
-installs the currently selected rosotacom version, stages the active project,
-runs delivery and isolation checks, collects artifacts, stops the run, and
-removes the remote workdir. Add `--interactive` for a local control tmux with
+`ota-smoke` accepts sessions and scenarios. It puts rosotacom on each peer,
+stages the active project, runs delivery and isolation checks, collects
+artifacts, stops the run, and removes the remote workdir. Add `--interactive`
+for a local control tmux with
 one attachable communication/catmux window per peer with a live status pane below
 each one. Scenario targets also get one native application-container window per
 scenario app. Stop an interactive run with `rosotacom ota-smoke TARGET
@@ -378,6 +404,29 @@ metadata is not available. Use `--keep-running` to leave components up,
 `--keep-workdir` to retain staged files, or `--reuse` to reuse an existing
 installation.
 
+#### What the peers run: `--install-mode`
+
+```bash
+# default: stage and install what you are running, uncommitted changes included
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot
+
+# rehearse a deployment: the peers install the published artefact
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode pin                # defaults to your own version
+rosotacom ota-smoke 2_native_chatter --peer a=workstation --peer b=robot \
+  --install-mode pin --install-pin 2.4
+```
+
+`source` is right while iterating on rosotacom itself — the peers run the code
+in front of you. `pin` is right when the run is meant to stand in for a real
+deployment: the peers install from the index, so a packaging defect (a file
+missing from the wheel, an undeclared dependency) fails in the rehearsal instead
+of on the target machine. `source` cannot catch that class of defect by
+construction, because it never builds the artefact that ships.
+
+The run manifest records which mode and which version the peers ran, so a result
+can be attributed to an artefact rather than to a working copy.
+
 ### Live status / debugging overview
 
 Enable a continuously-updated, per-topic pipeline overview by setting

{rosotacom_dev-2.2 → rosotacom_dev-2.4}/docs/ci.md

@@ -11,10 +11,14 @@ but one stable release line:
 
 - topic PRs are gated into the repository's active development branch by the
   GitHub checks below;
-- **`main`** is the stable release line;
+- every commit that lands there with green CI is published as a `X.Y.devN`
+  pre-release, so any commit is consumable without a release decision;
+- **`main`** is the stable line a repository synchronises upstream from;
 - moving development work to `main` is a deliberate maintainer operation and
   may require an external OTA gate;
-- releases are tags `vX.Y.Z` cut from `main` (see [release.md](release.md)).
+- releases are tags `vX.Y.Z` cut from a validated commit on the release line —
+  in this repository `develop`, its default branch (see
+  [release.md](release.md)).
 
 The OTA tier is not part of this repository's public CI. An operator-supplied
 external runner provides it as a manual promotion gate, as described generically

rosotacom_dev-2.4/docs/release-notes/v2.3.md

@@ -0,0 +1,34 @@
+# v2.3
+
+## Summary
+
+- Add `rosotacom resources path <name>`: report the host path of a packaged
+  resource (`ws`, `com_msgs`) for tooling outside the installation. rosotacom
+  installs into an isolated environment (pipx, or a project venv), so a consumer
+  cannot `import rosotacom` to compute such a path; this command is the
+  supported lookup.
+
+## Compatibility And Migration
+
+- No breaking changes. Consumers that hardcoded a path into a rosotacom checkout
+  should switch to `rosotacom resources path com_msgs`.
+
+## Known Issues
+
+- An installed `rosotacom-dev` reports its version as `0+unknown`: the package
+  looked up the distribution name `rosotacom`, which the fork no longer uses.
+  A version check against a pin therefore never matches, and
+  `ota-smoke --install-mode source` started from an installation writes that
+  string into the source bundle it builds on each peer, where it is not a valid
+  PEP 440 version and the remote build fails. Fixed in 2.4; this release cannot
+  be replaced because a published version is immutable.
+
+## Validation
+
+- `just lint`
+- `just typecheck`
+- `just test-unit`
+- `just test-contract`
+- `just docs`
+- `just package`
+- `just test-e2e-smoke`

rosotacom_dev-2.4/docs/release-notes/v2.4.md

@@ -0,0 +1,46 @@
+# v2.4
+
+## Summary
+
+- **Fix the reported version.** An installed distribution is now looked up
+  rather than assumed, so `rosotacom --version` reports the real version under
+  both published names (`rosotacom-dev` from this fork, `rosotacom` upstream).
+  Up to 2.3 every installed `rosotacom-dev` reported `0+unknown`, which made a
+  version check against a pin impossible and produced an unbuildable OTA source
+  bundle.
+- **Publish a development channel.** Every commit that lands on the development
+  branch with green CI is published as a `X.Y.devN` pre-release. Consuming this
+  package no longer means waiting for a release decision. `pip` ignores
+  pre-releases unless one is pinned exactly, so the stable line is unaffected.
+- **Stop duplicating packaging metadata.** The source bundle `ota-smoke` builds
+  when it runs from an installation derives its name, version, dependencies and
+  entry points from the installed distribution. The hand-written copy it used
+  before had drifted: `mcap` and `Pillow` were missing, so a peer prepared this
+  way imported fine and then failed inside the first MCAP or image code path.
+- **`ota-smoke --install-mode pin`.** Install a published release on each peer
+  instead of staging a source tree, so the rehearsal runs the artefact that
+  ships and can catch a packaging defect before a target machine does. The run
+  manifest records the mode and version the peers ran.
+- **`rosotacom resources path` covers `package` and `examples`**, which is how
+  pin mode remaps project config roots onto the peer's installation.
+
+## Compatibility And Migration
+
+- `ota-smoke` behaves as before unless `--install-mode pin` is passed.
+- The OTA deployment state file (`ota-deployment.yaml`) is now `schema_version:
+  2` and carries the install mode. State files written by an older version are
+  rejected; they are per-run artifacts, so start a new run.
+- Consumers pinning `rosotacom-dev==2.3` should move to `2.4` to get a usable
+  `--version`.
+
+## Validation
+
+- `just lint`
+- `just typecheck`
+- `just test-unit`
+- `just test-contract`
+- `just docs`
+- `just package`
+- `just test-e2e-smoke`
+- `tests/contract/test_ota_source_bundle.py` fails if the bundle metadata ever
+  diverges from `pyproject.toml` again.

rosotacom_dev-2.4/docs/release.md

@@ -0,0 +1,104 @@
+# Release
+
+This project publishes on two channels, and the difference between them is who
+decides, not how much is tested. Both build from the same commit and the same
+`just package`.
+
+| | Development channel | Stable release |
+|---|---|---|
+| Trigger | every commit that lands on `develop` with green CI | a `vX.Y.Z` tag |
+| Version | `X.Y.devN` (PEP 440 pre-release) | `X.Y.Z` |
+| Built by | `.github/workflows/dev-release.yml` | `.github/workflows/release.yml` |
+| Decided by | nobody — it follows the branch | a maintainer |
+| Reached by | an exact pin, or `--pre` | a normal install |
+
+The point of the development channel is that consuming this package should never
+be more expensive than consuming a checkout. Downstream repositories pin an
+exact version; without a continuous channel their only alternatives are to wait
+for a release decision or to bypass the package boundary, and the second one
+always wins in practice.
+
+`pip` does not resolve pre-releases unless asked, so a dev version can never
+reach a consumer by accident.
+
+## Version Source
+
+Package versions come from Git tags through `setuptools-scm`. The project does
+not keep a static version in `pyproject.toml` or `src/rosotacom/__init__.py`.
+
+After `v2.3`, commits on `develop` therefore build as `2.4.devN`: a
+pre-release *of the next* stable version, ordered before `2.4` itself.
+
+The distribution name is never hardcoded in the source. This code publishes as
+`rosotacom-dev` from the development fork and as `rosotacom` upstream, and
+`rosotacom/__init__.py` looks its own distribution up rather than assuming a
+name. Assuming one is what made every installed `rosotacom-dev` up to 2.3 report
+its version as `0+unknown`.
+
+The two "dev" in `rosotacom-dev==2.4.dev3` are not the same word, and only one
+of them is about maturity:
+
+- `-dev` in the **distribution name** says which line publishes it — the
+  development fork, as opposed to the FZI upstream that publishes as
+  `rosotacom`. It is part of every version of this package, stable ones
+  included: `rosotacom-dev==2.4` is a stable release.
+- `.dev3` in the **version** says how far along that particular artefact is
+  within this line: the third commit after `v2.3`, on the way to `2.4`.
+
+So `rosotacom-dev` alone tells you nothing about maturity. The version does.
+
+## Tags
+
+Stable releases use tags in this form:
+
+```text
+vX.Y.Z
+```
+
+Tags are cut from a validated commit on the release line — in this repository
+`develop`, which is also its default branch (see [ci.md](ci.md) for the branch
+model). Before cutting one, a maintainer should record the manual full-suite
+gate result described in [testing.md](testing.md). Push the tag from that exact
+commit.
+
+The tag build asserts that the version it produces is the version the tag names,
+and the development channel asserts the mirror image: it refuses to publish
+anything that is not a pre-release. Neither channel can publish under the
+other's identity.
+
+## Release Notes
+
+Each stable release must include:
+
+```text
+docs/release-notes/vX.Y.Z.md
+```
+
+Start from [docs/release-notes/TEMPLATE.md](release-notes/TEMPLATE.md). The
+release notes should summarize user-facing CLI, config, packaging, Docker,
+dependency, compatibility, and migration changes.
+
+## Publishing
+
+Tag pushes validate, publish through the repository's configured Trusted
+Publisher, and create a GitHub Release with the release notes, wheel, source
+distribution, and `SHA256SUMS`. Manual workflow dispatch validates and builds
+artifacts but does not publish; publishing a stable version requires a
+deliberate `vX.Y.Z` tag.
+
+Development-channel uploads use the same Trusted Publisher and the same
+`PYPI_PUBLISH_URL`. They are triggered by the CI workflow *completing
+successfully* on `develop`, not by the push itself, so a commit whose checks
+failed is never published. They skip the TestPyPI rehearsal: the dev channel is
+already the rehearsal.
+
+The target index is set per repository by the `PYPI_PUBLISH_URL` Actions
+variable, and authorization is granted by the Trusted Publisher registered for
+that repository. Both controls live in repository settings rather than shared
+git content.
+
+Publishing a release does not authorize or trigger synchronization to another
+repository. A downstream sync should use one stable tag as its boundary and
+must separately verify the exact tag SHA, release notes, successful release
+workflow, successful deployment, and generated artifacts before a PR is
+created.