Compatibility and Release Guide

Supported Development Matrix

• Rust: current stable and MSRV 1.85.
• Operating systems: Linux, macOS, and Windows.
• Python: CPython 3.11, 3.12, 3.13, and 3.14.
• Torrent modes: v1, v2 (BEP 52), and hybrid.

The matrix describes source and CI support. BTPC is pre-1.0 and no public package registry release has been made. Final wheels and native archives must pass clean artifact smoke tests before publication.

The release wheel targets are Linux x86-64/AArch64 with glibc 2.28 or later, macOS Intel/Apple Silicon, and Windows x86-64. The installation guide explains wheel selection and source-build requirements. The Python wheel contains the library; the CLI is distributed separately.

Python Runtime Model

BTPC currently requires the CPython global interpreter lock. The extension explicitly declares gil_used = true to PyO3, so a free-threaded CPython build may import it only with the GIL enabled. Long-running Rust work still releases the GIL, allowing independent BTPC operations to execute concurrently.

Subinterpreters are not supported. PyO3 0.29 rejects initialization from a second interpreter because extension-module state and cached Python objects are not yet per-interpreter. Use one main interpreter with threads or separate processes. Runtime callers can inspect btpc._native.__gil_required__ and btpc._native.__subinterpreters_supported__.

Interoperability

The committed fixture corpus covers mktorrent 1.1, mkbrr 1.23.0, torf-cli 5.2.1, and torrenttools 0.6.2 in every mode each tool supports. It also records malformed, noncanonical, and prior-fuzz cases with explicit accept/preserve/reject behavior. See the interoperability fixture documentation in the repository.

Stability

Before 1.0, Rust/Python APIs and CLI JSON schemas may evolve, but intentional compatibility changes must update specs, tests, documentation, and release notes. CLI exit categories and currently named JSON schema identifiers are tested. Unknown protocol byte strings remain byte-safe; text convenience views are best-effort only.

Artifact Expectations

Release wheels and archives must be produced from one verified version, install in clean environments, run all three torrent modes, inspect and magnetize output, and verify payloads. Publication should use least privilege and provenance. Normative requirements live in the release specification.

The manual workflow resolves a release tag to one commit before it starts checks and builds. It runs the full CI and documentation gates against that commit. Each wheel runs behavior checks and external Pyrefly/Pyright consumers in a fresh environment outside the checkout. A TestPyPI publication exercises the registry download and install path before the owner selects PyPI. See the release checklist for registry setup and publication steps.

The Cargo workspace package version is the single source. Start a release bump with make version VERSION=X.Y.Z, update CHANGELOG.md, then validate the tag with uv run python scripts/check_version.py --tag vX.Y.Z.

Performance Claims

No universal performance claim is valid without the canonical benchmark preflight, pinned competitor versions, repeated randomized measurements, raw result files, and machine/tool metadata. Reports must name limitations. See the benchmark documentation.

Optional metadata validation

BTPC preserves optional metadata as raw bytes while applying one domain policy in parse, create, edit, CLI, and Python surfaces. Empty tracker or web-seed URLs, empty tracker tiers, empty DHT hosts, DHT port 0, ports above 65535, malformed node pairs, non-integer or negative creation dates, and wrong bencode types for recognized text fields are errors. Ports 1 and 65535, duplicate non-empty values, empty text values, and non-UTF-8 text bytes are valid and lossless.

For compatibility, an explicitly empty announce-list is ignored in favor of a valid announce value and produces a validation warning. Creation never emits that warned form. An empty url-list means no web seeds and is accepted without a warning.