Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue