rosotacom-dev 2.3__tar.gz → 2.5.dev1__tar.gz

rosotacom_dev-2.5.dev1/.github/workflows/dev-release.yml

@@ -0,0 +1,157 @@
+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'
+    # Authorized by a Trusted Publisher registered with a blank environment. No
+    # token, no environment admin.
+    #
+    # PyPI matches the OIDC claims of the *workflow file*, so this needs its own
+    # registration for `dev-release.yml`; release.yml's does not cover it. Until
+    # that exists the build succeeds and the upload fails with
+    # `invalid-publisher`. See docs/github-repository-settings.md.
+    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.3 → rosotacom_dev-2.5.dev1}/.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.3 → rosotacom_dev-2.5.dev1}/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.3 → rosotacom_dev-2.5.dev1}/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.3 → rosotacom_dev-2.5.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.3
+Version: 2.5.dev1
 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.
 
@@ -428,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
@@ -440,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.3 → rosotacom_dev-2.5.dev1}/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.
 
@@ -383,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
@@ -395,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.3 → rosotacom_dev-2.5.dev1}/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.5.dev1/docs/github-repository-settings.md

@@ -0,0 +1,81 @@
+# GitHub Repository Settings
+
+These settings live outside git and must be verified separately in every
+repository using this shared codebase. The GitHub UI, CLI, and API remain the
+live source of truth.
+
+## Branch Protection
+
+Expected shared state:
+
+- `main` is the protected release line.
+- The repository's active development/default branch is protected.
+- Pull requests are required.
+- The required status check is `ci-success`.
+- Squash merges are allowed.
+- CodeQL default setup is enabled for Actions and Python.
+- The `release` environment and `PYPI_PUBLISH_URL` variable point at this
+  repository's intended package index.
+
+Verify:
+
+```bash
+REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+DEFAULT_BRANCH="$(gh repo view --repo "$REPO" --json defaultBranchRef --jq .defaultBranchRef.name)"
+gh ruleset list --repo "$REPO" --parents
+gh ruleset check "$DEFAULT_BRANCH" --repo "$REPO"
+gh ruleset check main --repo "$REPO"
+gh api "repos/$REPO/code-scanning/default-setup"
+gh variable get PYPI_PUBLISH_URL --repo "$REPO"
+```
+
+`gh ruleset check` reports which rules apply, not which status checks they
+require. A ruleset can be named for CI and still carry no
+`required_status_checks` rule, in which case auto-merge will merge a pull
+request whose checks are red. Read the rule types out directly:
+
+```bash
+gh api "repos/$REPO/rulesets" --jq '.[].id' \
+  | xargs -I{} gh api "repos/$REPO/rulesets/{}" \
+      --jq '{name, rules: [.rules[] | select(.type=="required_status_checks")
+             | .parameters.required_status_checks[].context]}'
+```
+
+Expected output names `ci-success`. An empty list is the drift this section
+exists to catch.
+
+## Trusted Publishers
+
+PyPI authorizes an upload by matching the OIDC claims of the *workflow file*
+that requests it, so a publisher registration is per filename, not per
+repository. This codebase publishes from two:
+
+| Workflow | Publishes | Registration |
+|---|---|---|
+| `release.yml` | stable `vX.Y.Z` tags | required |
+| `dev-release.yml` | `X.Y.devN` from the development branch | required for the development channel |
+
+A missing registration fails at upload with `invalid-publisher: valid token, but
+no corresponding publisher`, after a completely successful build. The message
+prints the claims it presented; `workflow_ref` is the filename to register.
+
+Register on PyPI under the project's *Publishing* settings: owner, repository,
+the workflow filename, and an empty environment (this codebase deliberately uses
+no GitHub environment, so that no repository sharing it needs environment-admin
+rights).
+
+## Repository Metadata
+
+Expected topics include `ros2`, `docker`, `robotics`, `teleoperation`, and
+`communication`.
+
+Verify:
+
+```bash
+gh repo view --json description,homepageUrl,repositoryTopics
+```
+
+## Drift Handling
+
+If GitHub state differs from this document, either update the live setting to
+match the documented contract or update this document in a PR if policy changed.

rosotacom_dev-2.5.dev1/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.5.dev1/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.