Organize documentation into focused user guides

This commit is contained in:
Jan Petykiewicz 2026-11-16 16:51:41 -08:00
commit a384bb2f89

View file

@ -1,51 +1,48 @@
# Building and validating a release
# Building releases
The source archive, Python wheels and standalone CLI are separate artifacts.
Python wheels contain `pheon` and its shared library; Cargo installation contains
the CLI. Neither installation searches for the other.
This guide is for maintainers producing source archives, Python wheels, and
standalone CLI artifacts. See [development](development.md) for local checks.
Build the source archive and then the wheel from that archive:
## Build from the source archive
```sh
python -m pip install build
python -m build
```
The default `build` invocation builds its wheel from the source archive. Both
carry the Cargo version, license and locked dependency resolution. A source build
requires Rust 1.88 or newer. The checkout selects current stable through
`rust-toolchain.toml`; `RUSTUP_TOOLCHAIN=1.88.0` selects the minimum compiler
explicitly for source-package builds. An installed wheel has no Rust runtime
requirement.
The default invocation builds the wheel from the source archive. Both use the
Cargo version, license, and locked dependencies. Source builds require Rust 1.88
or newer; the checkout selects stable. Use `RUSTUP_TOOLCHAIN=1.88.0` to check the
minimum compiler explicitly.
The package workflow builds the archive once, then uses cibuildwheel to build
from it and repair wheels for Linux x86-64/ARM64, macOS x86-64/ARM64 and Windows
x86-64. Repair uses the platform tools supplied by cibuildwheel. Wheels must keep
the `py3-none` interpreter/ABI tags and a platform tag, including an appropriate
manylinux tag for Linux releases. Local unrepaired `linux_*` wheels are development
artifacts, not portable Linux releases.
Python wheels contain the package and shared library. Cargo installation
provides the CLI. Neither installation discovers or depends on the other.
Each repaired wheel is tested on Python 3.11 through 3.14 without rebuilding it.
Tests run in isolated mode against the installed package and bundled library,
including an import that verifies integer packing does not import PyArrow. To
repeat that check locally after installing a wheel and PyArrow:
## Validate artifacts
The [package workflow](../.github/workflows/packages.yml) builds one source archive
and uses cibuildwheel to build and repair wheels for Linux and macOS x86-64/ARM64,
and Windows x86-64. Wheels use `py3-none` interpreter/ABI tags plus a platform tag.
Linux releases need an appropriate manylinux tag; unrepaired local `linux_*`
wheels are development artifacts.
The workflow tests each repaired wheel on Python 3.11–3.14 without rebuilding it.
Tests run in isolated mode against the installed package and bundled library.
To repeat the check after installing a wheel and PyArrow:
```sh
python -I /path/to/pheon/tools/check_installed.py
```
Unset `PHEON_LIBRARY` for artifact tests. It exists to select an explicit external
library during development, and version checks apply equally to that library.
The minimum Rust compiler and current stable compiler run native tests in both
debug and release modes. CLI artifacts contain the executable, license, README
and Git integration templates. They are tied to their build OS and architecture.
Unset `PHEON_LIBRARY` for artifact checks. Native checks cover minimum and stable
Rust in debug and release modes. Standalone CLI artifacts contain the executable,
license, README, documentation, and Git templates; each targets one OS and
architecture.
Workflows upload build artifacts only. They do not publish to PyPI, crates.io,
or a hosted release. The repository URL and checkout directory can be renamed
to `pheon` separately; no remote repository settings are changed by this work.
## Publish separately
The project rename provides no Python import shim or old CLI alias. Companion
releases must migrate their imports and dependencies together. The Python C API
version and Arrow layout version are currently 1. CLI reports use schema version
1 and retain the `klamath-object-v2` comparison profile and existing GDS layer-name
metadata marker.
Workflows upload artifacts; they do not publish to PyPI, crates.io, or a hosted
release. Review the artifacts and test results before publishing them.
Coordinate companion package dependencies when changing Python interfaces.
C API, Arrow layout, JSON schema, and comparison-profile versions have separate
contracts; see the [native API](native-api.md) and [report reference](diff-reports.md).