pheon/docs/releases.md
Jan Petykiewicz a723ba2265 Simplify Python bindings and package builds
Read each input path through one opened stream, including gzip detection, and
use direct numeric converter lookup while preserving byte-order handling and
caller data. Read the package version from installed metadata and report range
errors consistently as ValueError.

Require the supplied Cargo.lock instead of generating it during builds, use
the standard sdist command, and update package checks and development guides.

Validation: 15 Python tests pass against source and the rebuilt installed
wheel; the source archive and platform wheel build successfully.
2026-11-16 20:44:56 -08:00

48 lines
2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Building releases
This guide is for maintainers producing source archives, Python wheels, and
standalone CLI artifacts. See [development](development.md) for local checks.
## Build from the source archive
```sh
python -m pip install build
python -m build
```
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.
Python wheels contain the package and shared library. Cargo installation
provides the CLI. Neither installation discovers or depends on the other.
## Validate artifacts
The [package workflow](https://mpxd.net/code/jan/pheon/src/branch/master/.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 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.
## Publish separately
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).