nullpol 0.2.16__tar.gz → 0.3.0__tar.gz

{nullpol-0.2.16 → nullpol-0.3.0}/.github/ISSUE_TEMPLATE/feature-request.md

@@ -28,7 +28,6 @@ import nullpol
 
 # How you'd like to use the new feature
 result = nullpol.new_function(param="example")
-
 ```
 
 ## 🌈 Use Case & Benefits

{nullpol-0.2.16 → nullpol-0.3.0}/.github/workflows/ci.yml

@@ -11,8 +11,17 @@ jobs:
     test:
         strategy:
             matrix:
-                python-version: ['3.12', '3.13', '3.14']
+                # Locked resolutions run everywhere; the SPEC 0 minimum
+                # (lowest-direct) runs on ubuntu with the oldest supported
+                # Python, since floor versions predate newer interpreters'
+                # wheels.
+                python-version: ['3.13', '3.14']
                 os: [ubuntu-latest, macos-latest]
+                resolution: [locked]
+                include:
+                    - os: ubuntu-latest
+                      python-version: '3.13'
+                      resolution: lowest-direct
         runs-on: ${{ matrix.os }}
         steps:
             - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
@@ -26,10 +35,18 @@ jobs:
                   enable-cache: 'true'
 
             - name: Install dependencies
-              run: uv sync --group dev --frozen
+              shell: bash
+              env:
+                  RESOLUTION: ${{ matrix.resolution }}
+              run: |
+                  if [ "$RESOLUTION" = "lowest-direct" ]; then
+                      uv sync --group dev --upgrade --resolution lowest-direct
+                  else
+                      uv sync --group dev --frozen
+                  fi
 
             - name: Run tests with pytest
-              run: uv run --frozen pytest
+              run: uv run --no-sync pytest
 
             - name: Upload coverage to Codecov
               if: ${{ !cancelled() }}

{nullpol-0.2.16 → nullpol-0.3.0}/.github/workflows/codeql.yml

@@ -18,12 +18,12 @@ jobs:
             - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
 
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+              uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4
               with:
                   languages: python
 
             - name: Autobuild
-              uses: github/codeql-action/autobuild@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+              uses: github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d # v4
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+              uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4

{nullpol-0.2.16 → nullpol-0.3.0}/.github/workflows/scheduled-release.yml

@@ -4,6 +4,17 @@ on:
     schedule:
         - cron: '0 0 * * 2'
     workflow_dispatch:
+        inputs:
+            allow_major_bump:
+                description:
+                    'Let a breaking change bump 0.x.y into 1.0.0. Off by
+                    default: while the package is pre-1.0 a breaking change
+                    bumps the minor instead, because 1.x declares a stable API.
+                    Has no effect once the current major is >= 1, where a major
+                    bump is enforced anyway.'
+                required: false
+                default: false
+                type: boolean
 
 permissions:
     contents: write
@@ -20,7 +31,7 @@ jobs:
 
             - name: Check for new commits
               id: check_commits
-              uses: isaac-cf-wong/detect-git-changes-action@051225b2ef2faf2a02d61f16d1a027cdf941498d # v0.0.21
+              uses: isaac-cf-wong/detect-git-changes-action@9863c3c0ba155ed10b54072f711ae8807aedbc87 # v0.0.22
               with:
                   use-latest-tag: true
 
@@ -57,12 +68,32 @@ jobs:
 
             - name: Bump version and push tag
               id: tag_version
+              env:
+                  # The flag itself, or empty, so the shell never has to interpret a truth value.
+                  # The `inputs` context keeps a typed boolean as a boolean; `github.event.inputs`
+                  # would hand over the *string* `false`, which is truthy in a shell test. On a
+                  # `schedule` event `inputs` is absent, which is falsy -- the default.
+                  ALLOW_MAJOR_BUMP:
+                      ${{ inputs.allow_major_bump && '--allow-major-bump' || ''
+                      }}
               run: |
+                  set -euo pipefail
                   PREVIOUS_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
                   if [ "$PREVIOUS_TAG" = "none" ]; then
                     NEW_TAG="v0.1.0"
                   else
-                    NEW_TAG=$(uv run --frozen git-cliff --bumped-version --config cliff.toml 2>/dev/null)
+                    # git-cliff proposes; `release_version.py` decides. git-cliff sends a breaking
+                    # change straight to the next major, so at v0.x.y it answers v1.0.0 and would
+                    # publish a stable-API claim as a side effect. While the major is 0 that is
+                    # demoted to a minor bump unless this run was dispatched with allow_major_bump.
+                    # At 1.x and above the proposal is taken unchanged. git-cliff's stderr is no
+                    # longer discarded: an empty proposal must fail the run, not become a tag.
+                    PROPOSED_TAG=$(uv run --frozen git-cliff --bumped-version --config cliff.toml)
+                    NEW_TAG=$(uv run --frozen python scripts/release_version.py \
+                      --current "$PREVIOUS_TAG" \
+                      --proposed "$PROPOSED_TAG" \
+                      ${ALLOW_MAJOR_BUMP})
+                    echo "git-cliff proposed $PROPOSED_TAG; releasing $NEW_TAG"
                   fi
                   if ! git rev-parse "$NEW_TAG" >/dev/null 2>&1; then
                     echo "Creating annotated tag $NEW_TAG"

nullpol-0.3.0/.github/workflows/support_floor_update.yml

@@ -0,0 +1,64 @@
+name: Support floor update
+
+on:
+    schedule:
+        - cron: '0 6 1 * *' # monthly, 1st at 06:00 UTC
+    workflow_dispatch:
+
+concurrency:
+    group: support-floor-update
+    cancel-in-progress: false
+
+permissions:
+    contents: read
+
+jobs:
+    update-floors:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+              with:
+                  persist-credentials: false
+
+            - name: Apply support policy (spec0, from pyproject tool table)
+              id: policy
+              uses: isaac-cf-wong/dependency-support-policy-action@74dfcfcc079cd22b26713242940f65ba2b3c70c7 # v0.2.9
+              with:
+                  mode: update
+
+            # PRs created with the default GITHUB_TOKEN do not trigger CI, so
+            # the PR is created with a GitHub App installation token instead.
+            - name: Mint app token
+              if: steps.policy.outputs.changed == 'true'
+              id: app-token
+              uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
+              with:
+                  app-id: ${{ vars.APP_ID }}
+                  private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                  permission-contents: write
+                  permission-pull-requests: write
+
+            - name: Create or update pull request
+              if: steps.policy.outputs.changed == 'true'
+              id: pr
+              uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
+              with:
+                  token: ${{ steps.app-token.outputs.token }}
+                  branch: dependency-support-policy/update
+                  title: 'chore(deps): raise minimum supported versions'
+                  commit-message:
+                      'chore(deps): raise minimum supported versions'
+                  body: |
+                      Automated rolling support-floor update (SPEC 0).
+
+                      ```json
+                      ${{ steps.policy.outputs.dependency-floors-changed }}
+                      ```
+                  labels: dependencies
+
+            - name: Enable auto-merge
+              if: steps.pr.outputs.pull-request-number
+              env:
+                  GH_TOKEN: ${{ steps.app-token.outputs.token }}
+                  PR_NUMBER: ${{ steps.pr.outputs.pull-request-number }}
+              run: gh pr merge --squash --auto "$PR_NUMBER"

{nullpol-0.2.16 → nullpol-0.3.0}/.gitignore

@@ -192,3 +192,6 @@ local_config.*
 
 # Spellcheck files
 !.ignore_words.txt
+
+# CodeGraph index
+.codegraph/

{nullpol-0.2.16 → nullpol-0.3.0}/.pre-commit-config.yaml

@@ -17,9 +17,9 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.15.22
+      rev: v0.17.0
       hooks:
-          - id: ruff
+          - id: ruff-check
             args: [--fix, --config=pyproject.toml]
           - id: ruff-format
 
@@ -29,13 +29,13 @@ repos:
           - id: taplo-format
 
     - repo: https://github.com/crate-ci/typos
-      rev: v1.50.3
+      rev: v1.51.1
       hooks:
           - id: typos
             args: []
 
     - repo: https://github.com/rbubley/mirrors-prettier
-      rev: v3.9.9
+      rev: v3.9.10
       hooks:
           - id: prettier
 
@@ -48,7 +48,7 @@ repos:
                 - .markdownlint.yaml
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.12.23
+      rev: 0.13.0
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{nullpol-0.2.16 → nullpol-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullpol
-Version: 0.2.16
+Version: 0.3.0
 Summary: A package to perform model-independent polarization test of gravitational-wave signals.
 Project-URL: Documentation, https://isaac-cf-wong.github.io/nullpol/
 Project-URL: Source, https://github.com/isaac-cf-wong/nullpol
@@ -15,26 +15,25 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Requires-Dist: bilby-pipe>=1.9.0
-Requires-Dist: bilby>=2.8.0
-Requires-Dist: configargparse>=1.7.5
-Requires-Dist: gwpy>=4.0.1
-Requires-Dist: h5py>=3.16.0
-Requires-Dist: healpy>=1.19.0
-Requires-Dist: matplotlib>=3.10.9
-Requires-Dist: numba>=0.65.0
-Requires-Dist: numpy<2.4,>=2.3.5
-Requires-Dist: pandas>=3.0.3
-Requires-Dist: pycbc>=2.11.0
-Requires-Dist: rocket-fft>=0.3.1
-Requires-Dist: scipy<1.17.0,>=1.16.3
+Requires-Dist: bilby>=2.7.0
+Requires-Dist: configargparse>=1.7.1
+Requires-Dist: gwpy>=4.0.0
+Requires-Dist: h5py>=3.13.0
+Requires-Dist: healpy>=1.18.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: numba>=0.61.2
+Requires-Dist: numpy<2.6,>=2.2.0
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: pycbc>=2.10.0
+Requires-Dist: rocket-fft>=0.3.0
+Requires-Dist: scipy<1.19.0,>=1.15.0
 Provides-Extra: asimov
-Requires-Dist: asimov>=0.7.1; extra == 'asimov'
-Requires-Dist: cbcflow>=0.6.3; extra == 'asimov'
+Requires-Dist: asimov>=0.6.0; extra == 'asimov'
+Requires-Dist: cbcflow>=0.6.0; extra == 'asimov'
 Description-Content-Type: text/markdown
 
 # nullpol
@@ -79,15 +78,15 @@ pages for more details:
   [uv on GitHub](https://github.com/astral-sh/uv)
 - Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)
 
-**Note:** The package is built and tested against Python 3.12–3.14. When
+**Note:** The package is built and tested against Python 3.13–3.14. When
 creating a virtual environment with `uv`, specify the Python version to ensure
-compatibility: `uv venv --python 3.12`.
+compatibility: `uv venv --python 3.13`.
 
 ### From PyPI
 
 ```bash
 # Create a virtual environment (recommended with uv)
-uv venv --python 3.12
+uv venv --python 3.13
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv pip install nullpol
 ```
@@ -104,7 +103,7 @@ uv pip install nullpol[asimov]
 git clone https://github.com/isaac-cf-wong/nullpol.git
 cd nullpol
 # Create a virtual environment (recommended with uv)
-uv venv --python 3.12
+uv venv --python 3.13
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv sync
 ```

{nullpol-0.2.16 → nullpol-0.3.0}/README.md

@@ -40,15 +40,15 @@ pages for more details:
   [uv on GitHub](https://github.com/astral-sh/uv)
 - Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)
 
-**Note:** The package is built and tested against Python 3.12–3.14. When
+**Note:** The package is built and tested against Python 3.13–3.14. When
 creating a virtual environment with `uv`, specify the Python version to ensure
-compatibility: `uv venv --python 3.12`.
+compatibility: `uv venv --python 3.13`.
 
 ### From PyPI
 
 ```bash
 # Create a virtual environment (recommended with uv)
-uv venv --python 3.12
+uv venv --python 3.13
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv pip install nullpol
 ```
@@ -65,7 +65,7 @@ uv pip install nullpol[asimov]
 git clone https://github.com/isaac-cf-wong/nullpol.git
 cd nullpol
 # Create a virtual environment (recommended with uv)
-uv venv --python 3.12
+uv venv --python 3.13
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv sync
 ```

{nullpol-0.2.16 → nullpol-0.3.0}/cliff.toml

@@ -111,7 +111,7 @@ filter_commits = false
 # An array of link parsers for extracting external references, and turning them into URLs, using regex.
 link_parsers = []
 # Include only the tags that belong to the current branch.
-use_branch_tags = false
+use_branch_tags = true
 # Order releases topologically instead of chronologically.
 topo_order = false
 # Order releases topologically instead of chronologically.

{nullpol-0.2.16 → nullpol-0.3.0}/docs/installation.md

@@ -44,6 +44,6 @@ and documentation dependencies.
 
 ## Requirements
 
-- Python 3.12 or higher
+- Python 3.13 or higher
 - Key dependencies: bilby, bilby_pipe, gwpy, numpy, scipy, matplotlib
 - Full list available in `pyproject.toml`

{nullpol-0.2.16 → nullpol-0.3.0}/pyproject.toml

@@ -17,43 +17,42 @@ classifiers = [
   "Intended Audience :: Developers",
   "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 dynamic = ["version"]
 dependencies = [
-  "matplotlib>=3.10.9",
-  "numpy>=2.3.5,<2.4",
-  "bilby>=2.8.0",
+  "matplotlib>=3.10.0",
+  "numpy>=2.2.0,<2.6",
+  "bilby>=2.7.0",
   "bilby_pipe>=1.9.0",
-  "gwpy>=4.0.1",
-  "numba>=0.65.0",
-  "rocket-fft>=0.3.1",
-  "scipy>=1.16.3,<1.17.0",
-  "ConfigArgParse>=1.7.5",
-  "pycbc>=2.11.0",
-  "healpy>=1.19.0",
-  "h5py>=3.16.0",
-  "pandas>=3.0.3",
+  "gwpy>=4.0.0",
+  "numba>=0.61.2",
+  "rocket-fft>=0.3.0",
+  "scipy>=1.15.0,<1.19.0",
+  "ConfigArgParse>=1.7.1",
+  "pycbc>=2.10.0",
+  "healpy>=1.18.0",
+  "h5py>=3.13.0",
+  "pandas>=2.3.0",
 ]
 
 [project.optional-dependencies]
-asimov = ["asimov>=0.7.1", "cbcflow>=0.6.3"]
+asimov = ["asimov>=0.6.0", "cbcflow>=0.6.0"]
 
 [dependency-groups]
 dev = [
-  "ruff>=0.15.16",
-  "prek>=0.4.4",
-  "pytest-github-actions-annotate-failures>=0.4.0",
+  "ruff>=0.17.0",
+  "prek>=0.5.5",
+  "pytest-github-actions-annotate-failures>=0.4.2",
   "pytest-cov>=7.1.0",
-  "pytest-mock>=3.15.1",
-  "pytest>=9.0.3",
+  "pytest-mock>=3.16.0",
+  "pytest>=9.1.1",
 ]
-docs = ["zensical>=0.0.44", "mkdocstrings-python>=2.0.4"]
-build = ["hatch>=1.17.0"]
-release = ["git-cliff>=2.13.1"]
+docs = ["zensical>=0.0.69", "mkdocstrings-python>=2.0.9"]
+build = ["hatch>=1.18.1"]
+release = ["git-cliff>=2.14.2"]
 
 [project.urls]
 Documentation = "https://isaac-cf-wong.github.io/nullpol/"
@@ -80,6 +79,13 @@ tgrflow = 'nullpol.integrations.asimov.tgrflow:Collector'
 [project.entry-points.'asimov.hooks.applicator']
 tgrflow = 'nullpol.integrations.asimov.tgrflow:Applicator'
 
+[tool.dependency-support-policy]
+# Rolling support floors (SPEC 0): runtime lower bounds are raised on a schedule
+# by the support_floor_update.yml workflow, not by Renovate. See renovate.json.
+policy = "spec0"
+groups = ["project", "optional"]
+lock = "minimal"
+
 [tool.uv-dynamic-versioning]
 vcs = "git"      # default
 style = "semver" # or pep440, semver, etc.
@@ -98,7 +104,7 @@ fail_under = 0
 
 [tool.pytest.ini_options]
 addopts = "--cov-report xml:coverage.xml --cov src --cov-append -m 'not integration' --cov-report=term-missing"
-pythonpath = ["src"]
+pythonpath = ["src", "scripts"]
 testpaths = "tests"
 junit_family = "xunit2"
 markers = [
@@ -112,7 +118,7 @@ markers = [
 
 [tool.ruff]
 line-length = 120 # Matches Black's default
-target-version = "py312" # Align with CI (3.12–3.14) and requires-python (>=3.12)
+target-version = "py313" # Align with CI (3.13–3.14) and requires-python (>=3.13)
 lint.extend-select = [
   "E",
   "F",
@@ -141,6 +147,7 @@ lint.ignore = [
   "N806",    # Scientific variable names (e.g. F_matrix, wavelet_Nt)
   "PLR0912", # Too many branches in scientific algorithms
   "PLR0913", # Too many arguments in scientific APIs
+  "PLR0917", # Too many positional arguments in scientific APIs
   "PLR0915", # Too many statements in complex analysis code
 ]
 fix = true # Enable autofix
@@ -166,11 +173,13 @@ convention = "google"
   "PT018",
   "RUF043",
   "S110",
+  "BLE001",
 ]
 # S101: allow assert statements
 # ARG001: allow unused function arguments (common in fixtures)
 # PLC0415: allow import statements not at the top level
 # PLR2004: allow magic values in the unit tests
+# BLE001: allow broad exception handlers in tolerance tests
 "src/nullpol/analysis/result.py" = ["PLC0415", "S301"]
 "scripts/*" = ["SIM102", "PLC0415", "PLR2004"]
 

{nullpol-0.2.16 → nullpol-0.3.0}/renovate.json

@@ -15,6 +15,23 @@
         "schedule": ["before 4am on monday"]
     },
     "packageRules": [
+        {
+            "matchManagers": ["pep621"],
+            "matchDepTypes": [
+                "project.dependencies",
+                "project.optional-dependencies"
+            ],
+            "matchPackageNames": ["!numpy", "!scipy"],
+            "description": "Runtime lower bounds are owned by the dependency-support-policy (SPEC 0) workflow.",
+            "enabled": false
+        },
+        {
+            "matchManagers": ["pep621"],
+            "matchDepTypes": ["project.dependencies"],
+            "matchPackageNames": ["numpy", "scipy"],
+            "description": "Raise only the upper caps; widen keeps the SPEC 0 lower bounds untouched.",
+            "rangeStrategy": "widen"
+        },
         {
             "matchManagers": ["pep621"],
             "matchUpdateTypes": ["patch", "minor"],

nullpol-0.3.0/scripts/release_version.py

@@ -0,0 +1,150 @@
+"""Decide the version the next release ships under, given git-cliff's proposal.
+
+The scheduled release asks `git-cliff --bumped-version` for a tag. git-cliff's default sends a breaking
+change to the next major, which is right for a package that has promised an API and wrong for one that
+has not: at `v0.10.2` a breaking change answers `v1.0.0`. That would publish a stable-API claim as a
+side effect of a fix that only renames things.
+
+The rule this applies:
+
+    while the current version is `0.x.y`, a proposed major bump is demoted to a minor bump, unless the
+    release was run with `allow_major_bump`; once the current major is `>= 1`, git-cliff's answer stands
+    untouched.
+
+`cliff.toml` cannot express that. `[bump] breaking_always_bump_major = false` would also disable the
+enforced major bump at `>= 1`, which is the half worth keeping -- so the decision is post-processing on
+git-cliff's answer rather than configuration of it.
+
+Run as a script it takes the two versions and prints the answer, which is what the workflow uses:
+
+    python scripts/release_version.py --current v0.4.1 --proposed "$(git-cliff --bumped-version)"
+
+It lives in `scripts/` rather than in `src/`: it is release tooling and has no business in the wheel.
+`pyproject.toml` puts `scripts` on the test path so it is covered like anything else, because a wrong
+answer here is both expensive and silent -- a version cannot be unpublished, and nothing downstream
+would flag `1.0.0` as unintended.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+#: A release tag: an optional `v`, then exactly three dot-separated numbers. Deliberately strict --
+#: pre-release and build metadata are not used by this project's tags, and a tag shape nobody expected
+#: is a reason to stop the release rather than to guess at it.
+_VERSION = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)$")
+
+
+def _parse(version: str, *, described_as: str) -> tuple[int, int, int]:
+    """Return the numeric components of *version*.
+
+    Args:
+        version: The tag, with or without a leading `v`.
+        described_as: What to call it in the message, so a failure names which of the two was wrong.
+
+    Returns:
+        The major, minor and patch components.
+
+    Raises:
+        ValueError: If the version is not `<major>.<minor>.<patch>`, optionally `v`-prefixed.
+    """
+    matched = _VERSION.match(version.strip())
+    if matched is None:
+        raise ValueError(
+            f"could not read {described_as} {version!r} as a version: expected `<major>.<minor>.<patch>`, "
+            f"optionally prefixed with `v`. Refusing to guess, because the answer becomes a published tag."
+        )
+    major, minor, patch = matched.groups()
+    return int(major), int(minor), int(patch)
+
+
+def choose_version(*, current: str, proposed: str, allow_major_bump: bool = False) -> str:
+    """Return the version to release, holding the major back while the package is pre-1.0.
+
+    Args:
+        current: The latest released tag, e.g. from `git describe --tags --abbrev=0`.
+        proposed: What `git-cliff --bumped-version` suggests.
+        allow_major_bump: Take the proposal even if it crosses into `1.x`. This is the explicit
+            negotiation the rule leaves open; it does nothing once the current major is `>= 1`, where a
+            major bump is enforced anyway.
+
+    Returns:
+        The tag to create, carrying the `v` prefix if *proposed* had one.
+
+    Raises:
+        ValueError: If either version is unreadable, or the proposal is not ahead of the current version.
+    """
+    current_parts = _parse(current, described_as="the current version")
+    proposed_parts = _parse(proposed, described_as="the proposed version")
+    current_major, current_minor, _ = current_parts
+    proposed_major = proposed_parts[0]
+
+    # Checked before the rule is applied, because both numbers are only visible here. A proposal that is
+    # not ahead means git-cliff ran against the wrong history, and the release would either collide with
+    # an existing tag or publish a version that reads as older than the one before it.
+    if proposed_parts <= current_parts:
+        raise ValueError(
+            f"the proposed version {proposed!r} is not ahead of the current version {current!r}. "
+            f"git-cliff was run against unexpected history; releasing this would either collide with an "
+            f"existing tag or publish a version that reads as older."
+        )
+
+    # Normalised once, and it is the normalised form that is returned. Validating a stripped copy while
+    # returning the original meant `" v2.0.0 "` passed the parser and came back with its spaces, and
+    # `git check-ref-format 'refs/tags/ v2.0.0 '` refuses that -- so the release would have failed at the
+    # tag, with a message about ref format rather than about where the whitespace came from. The demoted
+    # path was never exposed to it, since it builds its answer out of parsed numbers. The general shape
+    # of the bug: validating a copy is not validating the thing you return.
+    #
+    # Not cosmetic in practice: the proposal arrives from `$(git-cliff ...)`, and command substitution
+    # strips trailing newlines but nothing else.
+    proposed = proposed.strip()
+    prefix = "v" if proposed.startswith("v") else ""
+
+    # The rule applies to exactly one situation: a 0.x package being pushed to 1.0 by a breaking change.
+    # Everything else -- 0.x staying in 0.x, and any bump at 1.x or above -- is git-cliff's answer.
+    demote = current_major == 0 and proposed_major > current_major and not allow_major_bump
+    if not demote:
+        return proposed
+
+    # A minor bump, with the patch reset: this is a 0.x minor release, not a major one wearing a smaller
+    # number. `0.10.1` -> `0.11.0`.
+    return f"{prefix}{current_major}.{current_minor + 1}.0"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Print the version to release.
+
+    Args:
+        argv: Command-line arguments, for testing; defaults to `sys.argv[1:]`.
+
+    Returns:
+        The process exit status: 0 on success, 2 if the versions could not be used.
+    """
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--current", required=True, help="the latest released tag")
+    parser.add_argument("--proposed", required=True, help="the tag git-cliff proposes")
+    parser.add_argument(
+        "--allow-major-bump",
+        action="store_true",
+        help="accept a bump into the next major while the current major is 0",
+    )
+    arguments = parser.parse_args(argv)
+    try:
+        print(
+            choose_version(
+                current=arguments.current,
+                proposed=arguments.proposed,
+                allow_major_bump=arguments.allow_major_bump,
+            )
+        )
+    except ValueError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())