build: rework version scheme to carry .dev0 on main

- `main` always carries the version planned for the next release with a `.dev0` suffix, e.g. `0.2.2.dev0`; per PEP 440 that sorts above the last official release (`0.2.1`), so a dev build never looks older than what's already published, and `.dev0` never ships in a wheel
- `make build` strips the suffix for a clean release; `make build-dev` (new) appends a unique `.dev<timestamp>+<sha>` instead, so two local wheel builds can be compared to see which is newer
- both targets route through `build.py`, which writes the resolved version into `_about.py` before `uv build`, then restores the file
- `make version` now reads `_about.py` as plain text instead of importing the package, so it no longer needs the project venv
- adds `COREAI_OPT_VERSION_EXTENSION` so a project that builds this repo as part of its own package can insert one extra release segment (e.g. `0.2.2.dev0` -> `0.2.2.1.dev0`) and keep its own, independent version numbering — `make build`/`make build-dev`/`make version` all work unchanged
- adds `tests/test_release_utils.py` covering the new helpers and the extension seam

Author: dengqiaoyu

Makefile

@@ -217,18 +217,23 @@ env-all: _maybe_patch_pyproject
 # Build
 # =============================================================================
 
-# Build the canonical, publishable distribution (wheel + sdist) via the uv build
-# frontend. `--no-sources` ignores [tool.uv.sources], so the artifact doesn't
-# depend on uv-specific index overrides — the recommended way to build for
-# publication. This is what the release workflow runs.
+# Build the canonical, publishable distribution (wheel + sdist): the on-tree
+# version with any `.dev` suffix stripped (e.g. 0.2.2.dev0 -> 0.2.2), via
+# `uv build --no-sources`. `--no-sources` ignores [tool.uv.sources], so the
+# artifact doesn't depend on uv-specific index overrides — the recommended way
+# to build for publication. This is what the release workflow runs. Routed
+# through build.py (like build-dev) so both targets share one code path; set
+# COREAI_OPT_VERSION_EXTENSION to insert an extra release segment (see
+# RELEASE.md).
 build:
-	@uv build --no-sources
+	@$(call use_env,VENV) && uv run --no-sync --active python $(SCRIPTS)/make/build.py --no-sources
 
-# Build the development distribution with build.py (standard version; build.py
-# also supports a PEP 440 .dev version via --dev). Used by contributors and the
-# smoke tests.
+# Build a development distribution with build.py: the release base with a
+# unique, timestamped PEP 440 dev suffix (e.g. 0.2.2.dev202607231430+abc1234).
+# Used by contributors, the smoke tests, and the nightly pipeline. Set
+# DEV_VERSION=... to use an exact version instead.
 build-dev:
-	@$(call use_env,VENV) && uv run --no-sync --active python $(SCRIPTS)/make/build.py
+	@$(call use_env,VENV) && uv run --no-sync --active python $(SCRIPTS)/make/build.py --dev
 
 # =============================================================================
 # Code Quality
@@ -326,9 +331,12 @@ distclean-all:
 set-auto-venv:
 	@$(SCRIPTS)/make/set_auto_venv.sh $(DEFAULT_VENV) $(SHELL_RC)
 
-# Show current version
+# Show the development version carried on the tree (e.g. 0.2.2.dev0). Reads
+# _about.py as plain text (no torch import needed), so no venv is required —
+# stdlib-only, like _maybe_patch_pyproject. Works for a repo that vendors this
+# one via COREAI_OPT_VERSION_EXTENSION (e.g. printing 0.2.2.1.dev0).
 version:
-	@python -c "exec(open('$(MAKEFILE_DIR)src/coreai_opt/_about.py').read()); print(__version__)"
+	@python3 $(SCRIPTS)/make/print_version.py
 
 # =============================================================================
 # Documentation

RELEASE.md

@@ -5,9 +5,53 @@ The OSS release process for Core AI Optimization is being defined. This page wil
 Available locally:
 
 ```bash
-make build      # build the package wheel
-make version    # show current version
+make build      # build the canonical, publishable wheel + sdist (uv build --no-sources)
+make build-dev  # build a timestamped dev wheel (e.g. 0.2.2.dev202607231430+abc1234)
+make version    # show the development version carried on the tree (e.g. 0.2.2.dev0)
 make clean      # remove build artifacts
 ```
 
+## Version scheme
+
+`main` always carries the version planned for the *next* release, so ongoing
+development is never mistaken for an already-published version and a release
+can be stabilized, tested, and published on its own branch independently of
+later changes on `main`. (The release-branch workflow itself — branch naming,
+tagging, backporting fixes to `main` — will be documented separately in the
+release schedule doc; this section covers only the version string mechanics.)
+
+Concretely, `main` carries the next planned release with a `.dev0` suffix in
+`src/coreai_opt/_about.py` (e.g. `0.2.2.dev0`). `.dev0` is only ever an on-tree
+marker — it never appears in a built wheel; both `make build` and
+`make build-dev` remove it before building.
+
+- `make build` strips the `.dev` suffix, e.g. `0.2.2.dev0` -> `0.2.2`. A
+  release is cut on a release branch by dropping the `.dev0` suffix in
+  `_about.py` and tagging `v0.2.2`; the release workflow verifies the tag
+  matches `_about.py`.
+- `make build-dev` replaces the suffix with a unique
+  `.dev<UTC-timestamp>+<short-sha>` — used by contributors, smoke tests, and
+  the nightly pipeline. `DEV_VERSION=<version>` uses that version exactly
+  instead.
+
+Sorting is preserved: `0.2.2.dev0 < 0.2.2.dev202607231430+abc1234 < 0.2.2`.
+
+### Extending the scheme downstream
+
+A repo that vendors this one under `external/` and includes this `Makefile` —
+building a single combined wheel from both trees — can insert one extra
+release segment by setting `COREAI_OPT_VERSION_EXTENSION=<segment>` (e.g.
+`"1"`) before calling `make build` / `make build-dev` / `make version`, all
+unchanged:
+
+- on tree: `0.2.2.dev0` + extension `1` -> `0.2.2.1.dev0`
+- `make build` -> `0.2.2.1`
+- `make build-dev` -> `0.2.2.1.dev<UTC-timestamp>+<short-sha>`
+
+There is still exactly one `_about.py` (this package's own, found at
+`src/coreai_opt/_about.py` or `external/src/coreai_opt/_about.py`); the
+extension is a plain string composed entirely in
+`scripts/release/release_utils.apply_version_extension` — no downstream file,
+package, or version-composition logic is involved.
+
 <!-- TODO: Document the chosen OSS release workflow (PyPI trusted publishing, twine upload, or uv publish). -->

changelog.d/53.changed

@@ -0,0 +1 @@
+Carry the next planned release with a `.dev0` suffix on `main` (e.g. `0.2.2.dev0`). `make build` strips the suffix for a clean release and `make build-dev` builds a unique, timestamped dev wheel (`0.2.2.dev<timestamp>+<shortsha>`). A repo that vendors this one can insert one extra release segment via the `COREAI_OPT_VERSION_EXTENSION` environment variable to extend the version scheme.

scripts/make/build.py

@@ -6,8 +6,20 @@
 """Build the coreai-opt package.
 
 Usage:
-    build.py          Build a standard wheel from the current version
-    build.py --dev    Build a dev wheel with a PEP 440 .dev version
+    build.py --no-sources    Build a release: the `.dev` suffix stripped, via
+                              `uv build --no-sources` (ignores [tool.uv.sources];
+                              the recommended way to build the publishable
+                              artifact). Called by `make build`.
+    build.py --dev            Build a dev wheel with a timestamped PEP 440 .dev
+                              version. Called by `make build-dev`.
+
+``main`` carries the next planned release with a ``.dev0`` suffix in ``_about.py``
+(e.g. ``0.2.2.dev0``); that suffix is only ever an on-tree marker and must never
+end up in a built wheel. This script computes the version to build, writes it
+into ``_about.py``, builds, then restores the file. A repo that vendors this one
+(building a single combined wheel from both trees) can insert one extra release
+segment via ``COREAI_OPT_VERSION_EXTENSION``; see
+``scripts/release/release_utils.apply_version_extension``.
 """
 
 from __future__ import annotations
@@ -24,43 +36,66 @@
 # internal-only scripts use the explicit `external.scripts.*` form instead.
 from scripts._utils import find_repo_root as _find_repo_root
 from scripts.release.release_utils import (
-    get_dev_release_version,
-    get_package_version,
+    ENV_VERSION_EXTENSION,
+    apply_version_extension,
+    read_version,
+    resolve_about_path,
+    resolve_build_version,
+    strip_dev_suffix,
     write_version,
 )
 
 
-def run_build() -> None:
-    """Run ``uv build`` to produce the wheel and sdist."""
+def run_build(*, no_sources: bool) -> None:
+    """Run ``uv build`` to produce the wheel and sdist.
+
+    Args:
+        no_sources: Pass ``--no-sources`` to ``uv build``, ignoring
+            ``[tool.uv.sources]`` so the artifact doesn't depend on uv-specific
+            index overrides — used for the publishable release build.
+    """
     print(f"Building package with python (version: {sys.version})...")
-    subprocess.run(["uv", "build"], check=True)
+    command = ["uv", "build", *(["--no-sources"] if no_sources else [])]
+    subprocess.run(command, check=True)
     print("Build complete! Check dist/ directory")
 
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Build the coreai-opt package.")
-    parser.add_argument(
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument(
         "--dev",
         action="store_true",
-        help="Build a dev wheel with a PEP 440 .dev version",
+        help="Build a dev wheel with a timestamped PEP 440 .dev version",
+    )
+    mode.add_argument(
+        "--no-sources",
+        action="store_true",
+        help="Build a release via `uv build --no-sources`",
     )
     return parser
 
 
 def main() -> None:
     args = _build_parser().parse_args()
-    if not args.dev:
-        run_build()
-        return
     repo_root = _find_repo_root(Path(__file__))
-    original_version = get_package_version(repo_root)
-    dev_version = os.environ.get("DEV_VERSION") or get_dev_release_version(original_version)
+
+    about = resolve_about_path(repo_root)
+    original = about.read_text(encoding="utf-8")  # exact bytes to restore afterwards
+    on_tree_version = read_version(original)  # e.g. "0.2.2.dev0"
+    extended = apply_version_extension(on_tree_version, os.environ.get(ENV_VERSION_EXTENSION))
+    release_base = strip_dev_suffix(extended)
+    build_version = resolve_build_version(
+        release_base,
+        dev=args.dev,
+        dev_version_override=os.environ.get("DEV_VERSION"),
+    )
     try:
-        write_version(repo_root, dev_version)
-        print(f"Dev version: {dev_version}")
-        run_build()
+        write_version(about, build_version)
+        print(f"Version: {build_version}")
+        run_build(no_sources=args.no_sources)
     finally:
-        write_version(repo_root, original_version)
+        about.write_text(original, encoding="utf-8", newline="\n")  # restore on-tree version
 
 
 if __name__ == "__main__":

scripts/make/print_version.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+
+# Copyright 2026 Apple Inc.
+#
+# Use of this source code is governed by a BSD-3-Clause license that can
+# be found in the LICENSE file or at https://opensource.org/licenses/BSD-3-Clause
+
+"""Print the development version carried on the tree (e.g. 0.2.2.dev0).
+
+Reads ``_about.py`` as plain text (no import, so no torch dependency). A repo
+that vendors this one can insert one extra release segment via
+``COREAI_OPT_VERSION_EXTENSION`` (e.g. printing ``0.2.2.1.dev0``); see
+``scripts/release/release_utils.apply_version_extension``.
+"""
+
+import os
+from pathlib import Path
+
+from scripts._utils import find_repo_root
+from scripts.release.release_utils import (
+    ENV_VERSION_EXTENSION,
+    apply_version_extension,
+    read_version,
+    resolve_about_path,
+)
+
+
+def main() -> None:
+    about = resolve_about_path(find_repo_root(Path(__file__)))
+    on_tree_version = read_version(about.read_text(encoding="utf-8"))
+    print(apply_version_extension(on_tree_version, os.environ.get(ENV_VERSION_EXTENSION)))
+
+
+if __name__ == "__main__":
+    main()