From 0051f694100a8b4979f854f49a0d8a82f8b00b1d Mon Sep 17 00:00:00 2001 From: Simon Birkholz Date: Thu, 10 Sep 2026 11:03:31 +0200 Subject: [PATCH 1/2] updating github workflows, and version documentation --- .github/workflows/ci.yml | 29 +++---- .github/workflows/release.yml | 99 +++++++++++------------- CHANGELOG.md | 9 ++- CONTRIBUTING.md | 30 +++++--- README.md | 4 +- scripts/check_changelog.py | 137 ---------------------------------- scripts/release_meta.py | 24 ------ 7 files changed, 84 insertions(+), 248 deletions(-) delete mode 100644 scripts/check_changelog.py delete mode 100644 scripts/release_meta.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e6653bd..25b4eb2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,19 +18,25 @@ jobs: name: Resolve versions runs-on: ubuntu-latest outputs: - version: ${{ steps.meta.outputs.version }} sdk: ${{ steps.meta.outputs.sdk }} - ruff: ${{ steps.meta.outputs.ruff }} + ruff: ${{ steps.pyproject.outputs.ruff }} steps: - uses: actions/checkout@v5 - - uses: actions/setup-python@v6 - with: - python-version: '3.11' - - name: Read pyproject.toml - id: meta - run: python scripts/release_meta.py >> "$GITHUB_OUTPUT" + id: pyproject + run: | + python3 - <<'PY' >> "$GITHUB_OUTPUT" + import tomllib + project = tomllib.load(open("pyproject.toml", "rb"))["project"] + print(f"version={project['version']}") + print("ruff=" + next(s for s in project["optional-dependencies"]["dev"] if s.startswith("ruff"))) + PY + + - id: meta + uses: cubert-hyperspectral/cuvis.docker/.github/actions/release-meta@main + with: + version: ${{ steps.pyproject.outputs.version }} lint: name: Lint @@ -60,12 +66,7 @@ jobs: with: fetch-depth: 0 - - uses: actions/setup-python@v6 - with: - python-version: '3.11' - - - name: Validate CHANGELOG.md structure - run: python scripts/check_changelog.py + - uses: cubert-hyperspectral/cuvis.docker/.github/actions/changelog@main - name: Require a changelog entry if: > diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 914beae..613ba19 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,12 +1,11 @@ name: Release -# Pushing a vMAJOR.MINOR.PATCH.TWEAK tag on main releases that commit. -# workflow_dispatch runs the same validation, build and TestPyPI publish as a -# dry run, and stops before PyPI. +# Pushing a vGENERATION.MAJOR.MINOR.PATCH tag on main releases that commit: sdist and wheel to +# TestPyPI, then PyPI, then a GitHub Release with the CHANGELOG.md section as notes. +# A pre-release tag (v3.6.0.0rc1) publishes to PyPI as a pre-release and creates no GitHub Release. on: push: tags: ['v*.*.*.*'] - workflow_dispatch: concurrency: group: release @@ -22,8 +21,8 @@ jobs: outputs: version: ${{ steps.meta.outputs.version }} sdk: ${{ steps.meta.outputs.sdk }} - ruff: ${{ steps.meta.outputs.ruff }} - is_tag: ${{ startsWith(github.ref, 'refs/tags/') }} + prerelease: ${{ steps.meta.outputs.prerelease }} + ruff: ${{ steps.pyproject.outputs.ruff }} steps: - uses: actions/checkout@v5 with: @@ -33,44 +32,30 @@ jobs: with: python-version: '3.11' - - name: Restrict manual dry runs to repository admins - if: github.event_name == 'workflow_dispatch' - uses: actions/github-script@v7 - with: - script: | - const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ - owner: context.repo.owner, - repo: context.repo.repo, - username: context.actor, - }); - if (data.permission !== "admin") { - core.setFailed(`Only repository admins may publish. (${context.actor} has: ${data.permission})`); - } - - name: Read pyproject.toml - id: meta - run: python scripts/release_meta.py >> "$GITHUB_OUTPUT" - - - name: Verify the tag points at a commit on main - if: startsWith(github.ref, 'refs/tags/') + id: pyproject run: | - git fetch --no-tags origin main - if ! git merge-base --is-ancestor HEAD origin/main; then - echo "Tag ${GITHUB_REF_NAME} is not an ancestor of main." - echo "Releases are cut from main; merge the release pull request first." - exit 1 - fi + python - <<'PY' >> "$GITHUB_OUTPUT" + import tomllib + project = tomllib.load(open("pyproject.toml", "rb"))["project"] + print(f"version={project['version']}") + print("ruff=" + next(s for s in project["optional-dependencies"]["dev"] if s.startswith("ruff"))) + PY - - name: Verify tag, version and changelog agree - if: startsWith(github.ref, 'refs/tags/') - run: python scripts/check_changelog.py --tag "${GITHUB_REF_NAME}" + - id: meta + uses: cubert-hyperspectral/cuvis.docker/.github/actions/release-meta@main + with: + version: ${{ steps.pyproject.outputs.version }} + tag: ${{ github.ref_name }} + + - uses: cubert-hyperspectral/cuvis.docker/.github/actions/tag-on-main@main - - name: Validate CHANGELOG.md structure - if: github.event_name == 'workflow_dispatch' - run: python scripts/check_changelog.py + - uses: cubert-hyperspectral/cuvis.docker/.github/actions/changelog@main + with: + version: ${{ steps.meta.outputs.base_version }} + prerelease: ${{ steps.meta.outputs.prerelease }} - name: Verify the version is not published yet - if: startsWith(github.ref, 'refs/tags/') env: VERSION: ${{ steps.meta.outputs.version }} run: | @@ -89,13 +74,22 @@ jobs: if released.get(version): sys.exit( f"cuvis=={version} is already on PyPI and cannot be replaced. " - "Bump TWEAK, move the CHANGELOG.md section, and tag again." + "Bump PATCH, move the CHANGELOG.md section, and tag again." ) print(f"cuvis=={version} is not published yet.") PY + - name: Verify the cuvis_pyil image for this SDK exists + env: + IMAGE: cubertgmbh/cuvis_pyil:${{ steps.meta.outputs.sdk }}-ubuntu24.04 + run: | + docker manifest inspect "$IMAGE" > /dev/null || { + echo "${IMAGE} does not exist. Release cuvis.pyil for SDK ${{ steps.meta.outputs.sdk }} first." + exit 1 + } + - name: Install ruff - run: python -m pip install "${{ steps.meta.outputs.ruff }}" + run: python -m pip install "${{ steps.pyproject.outputs.ruff }}" - name: Check formatting and lint rules run: | @@ -184,24 +178,25 @@ jobs: python-version: '3.11' - name: Confirm the version is downloadable from TestPyPI + env: + VERSION: ${{ needs.validate.outputs.version }} run: | for attempt in 1 2 3 4 5 6; do if python -m pip download --no-deps --dest /tmp/smoke \ --index-url https://test.pypi.org/simple/ \ - "cuvis==${{ needs.validate.outputs.version }}"; then + "cuvis==${VERSION}"; then ls -lh /tmp/smoke exit 0 fi echo "Not indexed yet, retrying in 30s (attempt ${attempt}/6)." sleep 30 done - echo "cuvis==${{ needs.validate.outputs.version }} never appeared on TestPyPI." + echo "cuvis==${VERSION} never appeared on TestPyPI." exit 1 publish-pypi: name: Publish to PyPI needs: [validate, publish-testpypi] - if: needs.validate.outputs.is_tag == 'true' runs-on: ubuntu-latest environment: pypi permissions: @@ -217,29 +212,23 @@ jobs: github-release: name: Create GitHub release needs: [validate, publish-pypi] + if: needs.validate.outputs.prerelease == 'false' runs-on: ubuntu-latest permissions: contents: write steps: - uses: actions/checkout@v5 - - uses: actions/setup-python@v6 - with: - python-version: '3.11' - - uses: actions/download-artifact@v4 with: name: distributions path: dist/ - - name: Extract the changelog section - id: notes - run: | - { - echo 'body<> "$GITHUB_OUTPUT" + - id: notes + uses: cubert-hyperspectral/cuvis.docker/.github/actions/changelog@main + with: + mode: extract + version: ${{ needs.validate.outputs.version }} - uses: softprops/action-gh-release@v2 with: diff --git a/CHANGELOG.md b/CHANGELOG.md index b83127d..8e8177b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,8 @@ All notable changes to the `cuvis` Python wrapper are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Entry wording follows the conventions in [CONTRIBUTING.md](CONTRIBUTING.md#changelog-conventions) - every API entry names the fully qualified symbol first, then states the change with one of the fixed predicates. -Versions are `MAJOR.MINOR.PATCH.TWEAK`. -`MAJOR.MINOR.PATCH` is the cuvis SDK release the wrapper targets; `TWEAK` counts wrapper-only revisions against that same SDK. +Versions are `GENERATION.MAJOR.MINOR.PATCH`. +`GENERATION.MAJOR.MINOR` is the cuvis SDK release the wrapper targets; `PATCH` counts wrapper-only revisions against that same SDK. See [CONTRIBUTING.md](CONTRIBUTING.md#version-scheme) for the full scheme. Entries for versions released before this file existed were reconstructed from the published PyPI artifacts and from an AST-level diff of the public `cuvis` API surface between the corresponding commits. @@ -16,8 +16,9 @@ Pre-releases (`b*`, `rc*`) are not listed. ### Added - `CI` - `.github/workflows/ci.yml` runs the test suite and a lint job enforcing `ruff check` and `ruff format --check` on every pull request and on every push to `develop` and `main`. -- `CI` - `.github/workflows/release.yml` is driven by `v*.*.*.*` tags: it validates the tag against `pyproject.toml` and against this file, builds, publishes to TestPyPI, and publishes to PyPI plus a GitHub Release after manual approval. -- `CI` - `scripts/check_changelog.py` validates this file's structure (header format, allowed section names, descending versions) and the tag/version/changelog agreement at release time. +- `CI` - `.github/workflows/release.yml` is driven by `v*.*.*.*` tags: it validates the tag against `pyproject.toml`, this file and the `cuvis_pyil` image, builds, publishes to TestPyPI, and publishes to PyPI plus a GitHub Release after manual approval. + Pre-release tags (`a`, `b`, `rc` suffix) publish to PyPI as pre-releases and create no GitHub Release. +- `CI` - the changelog structure and the tag/version/changelog agreement are validated by the shared actions in [cuvis.docker](https://github.com/cubert-hyperspectral/cuvis.docker). - `CONTRIBUTING.md` - documents the branch model, the version scheme, the changelog conventions and the release checklist. - `cuvis.BindingInfo` - new frozen dataclass with the fields `built_against: str`, `library_version: str`, `library_path: str` and `missing_symbols: Tuple[str, ...]`, the read-only property `is_complete: bool`, and a `__str__` rendering a report fit for a bug report. - `cuvis.SdkSettings` - new class, a `MutableMapping` of setting id to value that writes the SDK's `cuvis.settings` file, so the SDK configuration can be built in Python instead of maintained by hand. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1bd1895..09eb502 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,11 +22,11 @@ A pull request into `develop` or `main` must pass the `ci.yml` lint and test job ## Version scheme -Versions are `MAJOR.MINOR.PATCH.TWEAK`, always with all four components. +Versions are `GENERATION.MAJOR.MINOR.PATCH`, always with all four components, optionally followed by a pre-release suffix `a1`, `b1` or `rc1`. -- `MAJOR.MINOR.PATCH` is the cuvis SDK release this wrapper targets. +- `GENERATION.MAJOR.MINOR` is the cuvis SDK release this wrapper targets. It is not chosen by the wrapper; it follows the SDK. -- `TWEAK` counts wrapper-only revisions against that same SDK release, starting at `0`. +- `PATCH` counts wrapper-only revisions against that same SDK release, starting at `0`. Examples: @@ -40,8 +40,10 @@ Two consequences worth knowing: - PEP 440 treats `3.5.3.0` and `3.5.3` as the same version, so only one of the two forms may ever be published for a given release. Tags created before this scheme was written down use the three-component form (`v3.5.3` is release `3.5.3.0`); everything from `v3.5.3.2` onward is four-component. -- A `TWEAK` bump never widens or narrows the `cuvis-il` requirement in `pyproject.toml`. - If the interface layer requirement changes, the SDK it targets changed, so the change belongs in a `MAJOR.MINOR.PATCH` release. +- A `PATCH` bump never widens or narrows the `cuvis-il` requirement in `pyproject.toml`. + If the interface layer requirement changes, the SDK it targets changed, so the change belongs in a `GENERATION.MAJOR.MINOR` release. +- A pre-release (`3.6.0.0rc1`) runs the whole release pipeline and reaches PyPI as a pre-release, which `pip` ignores unless asked for with `--pre` or an exact pin. + It creates no GitHub Release; its changelog entries stay under `## [Unreleased]` until the final version, whose section then covers everything since the previous final release. The version lives in exactly one place: `[project].version` in `pyproject.toml`. The git tag is `v` followed by that value, and the release workflow refuses to publish when the two disagree. @@ -70,7 +72,7 @@ Widening it is a separate, self-contained pull request, never a side effect of a ## Changelog conventions Every user-visible change is recorded in `CHANGELOG.md` under `## [Unreleased]` in the same pull request that makes the change. -The file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and is validated by `scripts/check_changelog.py`, which CI runs on every pull request. +The file follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and is validated on every pull request by the shared `changelog` action from [cuvis.docker](https://github.com/cubert-hyperspectral/cuvis.docker). ### Structure @@ -123,6 +125,9 @@ The git history already records those, and they say nothing about the API. ## Releasing +Releases run in a fixed order across repositories; see the [cuvis.docker README](https://github.com/cubert-hyperspectral/cuvis.docker#release-order). +The `cuvis_pyil:-ubuntu24.04` image must exist before cuvis.python can release for that SDK; the workflow checks and stops otherwise. + ### One-time repository setup The release workflow depends on settings that live outside the repository: @@ -139,10 +144,11 @@ The release workflow depends on settings that live outside the repository: ### Regular release from `develop` 1. On `develop`, confirm which SDK version the wrapper targets and that `cuvis-il` in `pyproject.toml` matches it. -2. Rename `## [Unreleased]` to `## [X.Y.Z.W] - ` and add the SDK statement lines beneath it. +2. For a final version rename `## [Unreleased]` to `## [X.Y.Z.W] - ` and add the SDK statement lines beneath it. Add a fresh empty `## [Unreleased]` above it. -3. Set `[project].version` in `pyproject.toml` to `X.Y.Z.W`. -4. Run `ruff format --check . && ruff check . && pytest && python scripts/check_changelog.py`. + For a pre-release leave the entries under `## [Unreleased]`. +3. Set `[project].version` in `pyproject.toml` to `X.Y.Z.W` (or `X.Y.Z.WrcN`). +4. Run `ruff format --check . && ruff check . && pytest`. 5. Open a pull request `develop` -> `main` titled `release: vX.Y.Z.W` and merge it once CI is green. 6. Tag the merge commit on `main` and push the tag: @@ -152,15 +158,15 @@ The release workflow depends on settings that live outside the repository: git push origin vX.Y.Z.W ``` -7. `release.yml` validates the tag, builds, publishes to TestPyPI, and then waits for approval on the `pypi` environment before publishing to PyPI and creating the GitHub Release. +7. `release.yml` validates the tag, builds, publishes to TestPyPI, and then waits for approval on the `pypi` environment before publishing to PyPI and, for a final version, creating the GitHub Release. 8. Merge `main` back into `develop` so the release commit is an ancestor of both. ### Hotfix release from `main` -Same as above, except the branch is `hotfix/` cut from `main`, the pull request targets `main` directly, only `TWEAK` increases, and step 8 becomes mandatory rather than tidy-up. +Same as above, except the branch is `hotfix/` cut from `main`, the pull request targets `main` directly, only `PATCH` increases, and step 8 becomes mandatory rather than tidy-up. ### If a release goes wrong A published PyPI version cannot be replaced. -Fix forward with the next `TWEAK`; yank on PyPI only when the artifact is actively harmful. +Fix forward with the next `PATCH`; yank on PyPI only when the artifact is actively harmful. Delete the tag and re-tag only while the release workflow has not yet published anything. diff --git a/README.md b/README.md index 1cd90e6..a8985b7 100644 --- a/README.md +++ b/README.md @@ -66,8 +66,8 @@ For building the python bindings refer to [cuvis.pyil](https://github.com/cubert ## Versioning -Wrapper versions are `MAJOR.MINOR.PATCH.TWEAK`. -`MAJOR.MINOR.PATCH` is the Cuvis C SDK release this wrapper targets, and `TWEAK` counts wrapper-only +Wrapper versions are `GENERATION.MAJOR.MINOR.PATCH`. +`GENERATION.MAJOR.MINOR` is the Cuvis C SDK release this wrapper targets, and `PATCH` counts wrapper-only revisions against that same SDK; `3.5.3.1` is a wrapper fix on top of `3.5.3.0`, both for SDK 3.5.3. `main` always points at the latest released wrapper state, `develop` at the next release. diff --git a/scripts/check_changelog.py b/scripts/check_changelog.py deleted file mode 100644 index b65ad58..0000000 --- a/scripts/check_changelog.py +++ /dev/null @@ -1,137 +0,0 @@ -#!/usr/bin/env python3 -"""Validate CHANGELOG.md against the conventions in CONTRIBUTING.md. - -Without arguments the structure is checked. -With --tag the tag, the pyproject version and the newest release section must all agree. -With --extract the body of one release section is written to stdout, for the GitHub Release text. -""" - -import argparse -import re -import sys -import tomllib -from pathlib import Path - -SECTIONS = ("Added", "Changed", "Deprecated", "Removed", "Fixed", "Security") - -UNRELEASED = re.compile(r"^## \[Unreleased\]$") -RELEASE = re.compile(r"^## \[(\d+(?:\.\d+)*(?:\.post\d+)?)\] - (\d{4}-\d{2}-\d{2})$") -SECTION = re.compile(r"^### (.+)$") -BULLET = re.compile(r"^- \S") -CONTINUATION = re.compile(r"^ {2}\S") - - -def version_key(version): - """Order releases the way PEP 440 does, so 3.5.3 and 3.5.3.0 compare equal.""" - base, _, post = version.partition(".post") - padded = (tuple(int(p) for p in base.split(".")) + (0,) * 8)[:8] - return padded, int(post or 0) - - -def releases(lines): - """Yield (line_number, version, date) for every release header.""" - return ( - (no, *match.groups()) - for no, line in enumerate(lines, 1) - if (match := RELEASE.match(line)) - ) - - -def section_errors(no, heading, seen): - if heading not in SECTIONS: - yield f"{no}: unknown section '{heading}', expected one of {', '.join(SECTIONS)}" - elif heading in seen: - yield f"{no}: section '{heading}' appears twice in the same release" - elif seen and SECTIONS.index(heading) < max(SECTIONS.index(s) for s in seen): - yield f"{no}: section '{heading}' is out of order, expected {' < '.join(SECTIONS)}" - - -def structure_errors(lines): - """Report every convention violation, one message per offending line.""" - if not any(map(UNRELEASED.match, lines)): - yield "0: no '## [Unreleased]' section; add one so the next change has a home" - - versions = [(no, v) for no, v, _ in releases(lines)] - for (_, previous), (no, version) in zip(versions, versions[1:]): - if version_key(version) == version_key(previous): - yield f"{no}: version {version} duplicates {previous} (equal under PEP 440)" - elif version_key(version) > version_key(previous): - yield f"{no}: version {version} must sort below {previous}" - - seen = set() - in_section = False - for no, line in enumerate(lines, 1): - if line.startswith("## "): - if not (UNRELEASED.match(line) or RELEASE.match(line)): - yield f"{no}: release header must be '## [] - '" - seen, in_section = set(), False - elif match := SECTION.match(line): - yield from section_errors(no, match.group(1), seen) - if match.group(1) in SECTIONS: - seen.add(match.group(1)) - in_section = True - elif ( - in_section - and line.strip() - and not (BULLET.match(line) or CONTINUATION.match(line)) - ): - yield f"{no}: expected a '- ' bullet or a two-space continuation line" - - -def body(lines, version): - """The lines of one release section, without its header.""" - starts = [ - no for no, v, _ in releases(lines) if version_key(v) == version_key(version) - ] - if not starts: - raise SystemExit(f"no release section for version {version} in CHANGELOG.md") - rest = lines[starts[0] :] - end = next( - (i for i, line in enumerate(rest) if i and line.startswith("## ")), len(rest) - ) - return "\n".join(rest[1:end]).strip() - - -def main(): - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("--changelog", type=Path, default=Path("CHANGELOG.md")) - parser.add_argument("--pyproject", type=Path, default=Path("pyproject.toml")) - parser.add_argument( - "--tag", help="release tag (vX.Y.Z.W) that must match version and changelog" - ) - parser.add_argument( - "--extract", help="print the body of this release section and exit" - ) - args = parser.parse_args() - - lines = args.changelog.read_text(encoding="utf-8").splitlines() - - if args.extract: - print(body(lines, args.extract)) - return 0 - - errors = list(structure_errors(lines)) - - if args.tag: - version = tomllib.loads(args.pyproject.read_text(encoding="utf-8"))["project"][ - "version" - ] - newest = next((v for _, v, _ in releases(lines)), None) - if args.tag != f"v{version}": - errors.append( - f"0: tag {args.tag} does not match pyproject version {version}" - ) - if newest != version: - errors.append( - f"0: newest changelog release is {newest}, expected {version}" - ) - if not re.fullmatch(r"\d+\.\d+\.\d+\.\d+", version): - errors.append(f"0: version {version} is not MAJOR.MINOR.PATCH.TWEAK") - - for error in errors: - print(f"{args.changelog}:{error}", file=sys.stderr) - return 1 if errors else 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/scripts/release_meta.py b/scripts/release_meta.py deleted file mode 100644 index 6b6fb28..0000000 --- a/scripts/release_meta.py +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env python3 -"""Print the pyproject.toml facts the workflows need, as GITHUB_OUTPUT lines. - -Keeps the SDK container tag and the ruff pin derived from the single version -source instead of duplicated into the workflow YAML. -""" - -import tomllib -from pathlib import Path - -project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"] -version = project["version"] - -facts = { - "version": version, - "sdk": ".".join(version.split(".")[:3]), - "ruff": next( - spec - for spec in project["optional-dependencies"]["dev"] - if spec.startswith("ruff") - ), -} - -print("\n".join(f"{key}={value}" for key, value in facts.items())) From 2e76f33d71f376ead12d67938850b0771d397b66 Mon Sep 17 00:00:00 2001 From: Simon Birkholz Date: Thu, 10 Sep 2026 11:35:26 +0200 Subject: [PATCH 2/2] updating version number to match against --- .github/workflows/release.yml | 31 +++++++++++++++++++++++++++++++ CHANGELOG.md | 2 ++ CONTRIBUTING.md | 5 +++++ pyproject.toml | 4 ++-- 4 files changed, 40 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 613ba19..2133f59 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -79,6 +79,37 @@ jobs: print(f"cuvis=={version} is not published yet.") PY + - name: Verify the cuvis-il requirement agrees with the version + env: + VERSION: ${{ steps.meta.outputs.version }} + SDK: ${{ steps.meta.outputs.sdk }} + run: | + python -m pip install packaging + python - <<'PY' + import os, sys, tomllib + from packaging.requirements import Requirement + from packaging.version import Version + + version, sdk = Version(os.environ["VERSION"]), os.environ["SDK"] + project = tomllib.load(open("pyproject.toml", "rb"))["project"] + spec = next(Requirement(d) for d in project["dependencies"] if d.startswith("cuvis-il")).specifier + + if Version(sdk) not in spec: + sys.exit(f"cuvis-il{spec} does not accept {sdk}, the SDK this release targets.") + + # PEP 440 sorts 3.6.0.0rc1 below 3.6.0, so only a bound that names a pre-release + # can reach one; naming one also opens the whole range to pre-releases, which a + # final release must not ship. + if bool(spec.prereleases) != version.is_prerelease: + opens = "opens" if spec.prereleases else "does not open" + sys.exit( + f"cuvis-il{spec} {opens} to pre-releases but {version} is " + f"{'a pre-release' if version.is_prerelease else 'final'}. " + f"A pre-release needs a bound naming one, as in >={sdk}a0; a final needs >={sdk}." + ) + print(f"cuvis-il{spec} agrees with {version}.") + PY + - name: Verify the cuvis_pyil image for this SDK exists env: IMAGE: cubertgmbh/cuvis_pyil:${{ steps.meta.outputs.sdk }}-ubuntu24.04 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e8177b..8322583 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ Pre-releases (`b*`, `rc*`) are not listed. - `CI` - `.github/workflows/release.yml` is driven by `v*.*.*.*` tags: it validates the tag against `pyproject.toml`, this file and the `cuvis_pyil` image, builds, publishes to TestPyPI, and publishes to PyPI plus a GitHub Release after manual approval. Pre-release tags (`a`, `b`, `rc` suffix) publish to PyPI as pre-releases and create no GitHub Release. - `CI` - the changelog structure and the tag/version/changelog agreement are validated by the shared actions in [cuvis.docker](https://github.com/cubert-hyperspectral/cuvis.docker). +- `CI` - the release refuses to publish when the `cuvis-il` requirement disagrees with the version: it must accept the SDK the version targets, and it may open to pre-releases only when the release is itself a pre-release. - `CONTRIBUTING.md` - documents the branch model, the version scheme, the changelog conventions and the release checklist. - `cuvis.BindingInfo` - new frozen dataclass with the fields `built_against: str`, `library_version: str`, `library_path: str` and `missing_symbols: Tuple[str, ...]`, the read-only property `is_complete: bool`, and a `__str__` rendering a report fit for a bug report. - `cuvis.SdkSettings` - new class, a `MutableMapping` of setting id to value that writes the SDK's `cuvis.settings` file, so the SDK configuration can be built in Python instead of maintained by hand. @@ -37,6 +38,7 @@ Pre-releases (`b*`, `rc*`) are not listed. ### Changed - Whole tree reformatted with `ruff format`; no behaviour change. +- `pyproject.toml` - the `cuvis-il` requirement moved from `>=3.5.0,<3.6.0` to `>=3.6.0a0,<3.7.0`, so the wrapper targets cuvis SDK 3.6 and accepts the pre-releases of that SDK line. - `README.md` - documents the version scheme, and lists Python 3.14 among the supported interpreters as `pyproject.toml` already did. - `prebuild.py` - writes `cuvis/git-hash.txt` instead of `git-hash.txt` at the repository root, so the file lands inside the package that declares it as package data. - `cuvis.General.init` - parameter `settings_path` type changed from `str` to `Union[str, Path, SdkSettings]`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09eb502..b8a5cc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,11 @@ Two consequences worth knowing: Tags created before this scheme was written down use the three-component form (`v3.5.3` is release `3.5.3.0`); everything from `v3.5.3.2` onward is four-component. - A `PATCH` bump never widens or narrows the `cuvis-il` requirement in `pyproject.toml`. If the interface layer requirement changes, the SDK it targets changed, so the change belongs in a `GENERATION.MAJOR.MINOR` release. + The one exception is the pre-release bound below, which is tied to the release being a pre-release rather than to the SDK. +- A pre-release opens the `cuvis-il` requirement at `a0`, as in `>=3.6.0a0,<3.7.0`; the final release closes it again to `>=3.6.0,<3.7.0`. + The `a0` is load-bearing. + PEP 440 sorts `3.6.0.0rc1` below `3.6.0`, so a `>=3.6.0` bound cannot reach a pre-release of that SDK at all, and naming a pre-release in the bound is also what permits `pip` to consider pre-releases without `--pre`. + The cost is that `pip` then prefers a pre-release of a later SDK in the same line, `3.6.1.0rc1`, over the current final `3.6.0.0`. - A pre-release (`3.6.0.0rc1`) runs the whole release pipeline and reaches PyPI as a pre-release, which `pip` ignores unless asked for with `--pre` or an exact pin. It creates no GitHub Release; its changelog entries stay under `## [Unreleased]` until the final version, whose section then covers everything since the previous final release. diff --git a/pyproject.toml b/pyproject.toml index 2599ca3..f924437 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "cuvis" -version = "3.5.3.2" +version = "3.6.0.0rc1" description = "CUVIS Python SDK." readme = "README.md" requires-python = ">=3.10" @@ -14,7 +14,7 @@ authors = [ ] dependencies = [ - "cuvis-il>=3.5.0,<3.6.0", + "cuvis-il>=3.6.0a0,<3.7.0", "setuptools; python_version>='3.12'" # Only for Python 3.12+ ]