Use 4th release segment 9.6.2.N for fvtk versioning (#102)

Author: banesullivan

ci/cibw/fvtk_backend.py

@@ -74,11 +74,12 @@
 
 
 def _version_suffix() -> str:
-    """Tag-driven ``VTK_VERSION_SUFFIX`` via setuptools_scm (start at post0).
+    """Tag-driven ``VTK_VERSION_SUFFIX`` via setuptools_scm (start at 9.6.2.0).
 
-    The PyPI version is driven by git tags: tag ``9.6.2.post0`` -> wheel
-    ``9.6.2.post0``; commits past a tag get ``9.6.2.post1.devN`` (never published,
-    publish only runs on a release tag). setuptools_scm derives the full PEP 440
+    The PyPI version is driven by git tags: tag ``9.6.2.0`` -> wheel ``9.6.2.0``;
+    commits past a tag get ``9.6.2.1.devN`` (never published, publish only runs on
+    a release tag). The 4th segment is a normal PEP 440 release component (NOT a
+    .post; see docs/versioning.md). setuptools_scm derives the full PEP 440
     version from the repo's tags (honouring ``SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FVTK``
     if set); VTK's setup.py.in composes ``{VTK_BASE_VERSION}.{VTK_VERSION_SUFFIX}``,
     so we hand it only the suffix (everything past the base + dot).
@@ -95,7 +96,7 @@ def _version_suffix() -> str:
             dist_name="fvtk",  # so SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FVTK is honoured
             version_scheme="guess-next-dev",
             local_scheme="no-local-version",  # keep dev versions PyPI-upload-clean
-            fallback_version=f"{VTK_BASE_VERSION}.post0.dev0",
+            fallback_version=f"{VTK_BASE_VERSION}.0.dev0",
         )
     except Exception as exc:  # noqa: BLE001 - any scm/git failure -> safe default
         print(
@@ -111,8 +112,8 @@ def _version_suffix() -> str:
     if not version.startswith(prefix):
         raise RuntimeError(
             f"fvtk_backend: scm version {version!r} does not start with the VTK "
-            f"base {VTK_BASE_VERSION!r}; tag releases as {VTK_BASE_VERSION}.postN "
-            f"(e.g. {VTK_BASE_VERSION}.post0)."
+            f"base {VTK_BASE_VERSION!r}; tag releases as {VTK_BASE_VERSION}.N "
+            f"(e.g. {VTK_BASE_VERSION}.0)."
         )
     suffix = version[len(prefix):]
     print(f"fvtk_backend: scm version {version} -> VTK_VERSION_SUFFIX={suffix}", flush=True)

docs/versioning.md

@@ -0,0 +1,98 @@
+# Versioning and releases
+
+fvtk publishes two PyPI projects — **`fvtk`** (the runtime wheel) and
+**`fvtk-sdk`** (headers + CMake config + import libraries). They share one
+version, derived from a single git tag.
+
+## The scheme: `9.6.2.N`
+
+The version is the VTK base this fork is a drop-in for (**`9.6.2`**, frozen) plus
+a **4th release segment `N`** — the fvtk iteration:
+
+```
+9.6.2.0    first fvtk release of VTK 9.6.2
+9.6.2.1    next fvtk release (perf levers, opt-in filters, fixes)
+9.6.2.2    ...
+```
+
+`N` is a normal [PEP 440](https://peps.python.org/pep-0440/) release component,
+incremented every time we ship. The base stays `9.6.2` for the life of the fork
+against VTK 9.6.2; it only changes when we rebase onto a new upstream VTK (then
+`9.7.0.0`, etc.).
+
+### Why a 4th segment and not `.postN`
+
+fvtk ships **real code changes** between releases (devirtualization, LTO/PGO,
+opt-in fast filters, threading fixes). PEP 440 reserves `.postN` for
+*packaging-only* corrections with **no code changes**, so `.post` would
+misdescribe every release as "repackaged VTK 9.6.2." A normal release segment is
+honest, and it also keeps the door open for **publishable pre-releases** —
+`9.6.2.1rc1` is valid, whereas an RC *of* a post-release is not expressible.
+
+### Special case: bare `9.6.2`
+
+A tag of exactly `9.6.2` (no 4th segment) builds with an empty
+`VTK_VERSION_SUFFIX` — reserved for an unmodified, byte-exact official build.
+Normal fork releases always carry the `.N` segment.
+
+## How a version is computed
+
+`setuptools_scm` derives the version from git tags (config in
+`pyproject.toml` `[tool.setuptools_scm]`; consumed by
+`ci/cibw/fvtk_backend.py::_version_suffix`, which feeds everything past `9.6.2.`
+to VTK's `setup.py.in` as `VTK_VERSION_SUFFIX`). `fvtk-sdk` calls the *same*
+function (`ci/build-sdk.sh`), so the two wheels always match.
+
+- **On a tag** (`9.6.2.1`) → exact version `9.6.2.1`.
+- **Between tags** → `9.6.2.N.devM` (next-iteration dev). These build but are
+  **never published** — publish runs only on a release. `local_scheme =
+  no-local-version` keeps them PyPI-upload-clean.
+
+## Cutting a release
+
+Publishing is gated on a **published GitHub Release**, not a bare tag push.
+A `git push --tags` alone does **not** publish.
+
+1. Pick the next segment `N` (last published `9.6.2.K` → tag `9.6.2.{K+1}`; very
+   first release → `9.6.2.0`).
+2. Draft a **GitHub Release** in `pyvista/fvtk` and create the tag `9.6.2.N` from
+   it (target the commit you want to ship).
+3. Publishing the Release fires:
+   - `.github/workflows/ci.yml` → builds the shipped wheels (Linux LTO abi3 +
+     macOS + Windows), runs the bit-exact / pixel-exact gates, then the
+     `publish` job (environment **`pypi`**) trusted-publishes `fvtk`.
+   - `.github/workflows/sdk.yml` → builds + `publish-sdk` (environment
+     **`pypi-sdk`**) trusted-publishes `fvtk-sdk`.
+4. Both use OIDC trusted publishing (no stored tokens). PyPI trusted-publisher
+   config:
+
+   | project    | workflow  | environment |
+   |------------|-----------|-------------|
+   | `fvtk`     | `ci.yml`  | `pypi`      |
+   | `fvtk-sdk` | `sdk.yml` | `pypi-sdk`  |
+
+   For the **first** release of each project (before it exists on PyPI), register
+   a **pending** trusted publisher on PyPI with these values.
+
+## Downstream pinning
+
+`9.6.2.N` behaves like any release version — a bare `pip install fvtk` always
+resolves the latest stable (pre-releases excluded by default):
+
+```
+fvtk==9.6.2.1        # exact build
+fvtk==9.6.2.*        # any fvtk built against VTK 9.6.2
+fvtk~=9.6.2.0        # compatible release: >=9.6.2.0, <9.6.3
+fvtk>=9.6.2.1        # floor
+```
+
+Downstream libraries that need a specific fork iteration pin `==9.6.2.N`; those
+that only care about the VTK base pin `==9.6.2.*`. Pin `fvtk` and `fvtk-sdk` to
+the same version — they are released in lockstep.
+
+## Rebasing onto a new VTK
+
+When fvtk moves to a new upstream VTK (say 9.7.0), bump `VTK_BASE_VERSION`
+(`ci/cibw/fvtk_backend.py`) and the base in `pyproject.toml`, then restart the
+segment at `9.7.0.0`. PEP 440 ordering keeps the lines distinct:
+`9.6.2.5 < 9.7.0.0`.

pyproject.toml

@@ -19,17 +19,20 @@ requires = ["setuptools<81", "wheel", "setuptools_scm>=8"]
 build-backend = "fvtk_backend"
 backend-path = ["ci/cibw"]
 
-# Tag-driven PyPI versioning (start at post0). The base is pinned to the VTK
-# version this fork is a drop-in for (9.6.2); git tags add the post segment, so a
-# release tagged `9.6.2.post0` publishes `fvtk 9.6.2.post0`, `9.6.2.post1`, etc.
+# Tag-driven PyPI versioning (start at 9.6.2.0). The base is pinned to the VTK
+# version this fork is a drop-in for (9.6.2); git tags add a 4th release segment
+# (the fvtk iteration), so a release tagged `9.6.2.0` publishes `fvtk 9.6.2.0`,
+# `9.6.2.1`, etc. The 4th segment is a normal PEP 440 release component (NOT a
+# .post — fvtk ships code changes, and a real release segment also unlocks
+# publishable RCs like `9.6.2.1rc1`). See docs/versioning.md for the full scheme.
 # fvtk_backend reads this via setuptools_scm.get_version() and feeds the suffix
 # (everything past `9.6.2.`) to VTK's setup.py.in as VTK_VERSION_SUFFIX. Commits
-# between tags get `9.6.2.postN.devM` (never published — publish runs only on a
+# between tags get `9.6.2.N.devM` (never published — publish runs only on a
 # release tag). local_scheme = no-local-version keeps dev versions PyPI-clean.
 [tool.setuptools_scm]
 version_scheme = "guess-next-dev"
 local_scheme = "no-local-version"
-fallback_version = "9.6.2.post0.dev0"
+fallback_version = "9.6.2.0.dev0"
 
 [project]
 name = "fvtk"