ADR-0004: Packages release independently under their own tags and version ranges
Status: accepted (2026-09-10), revision accepted (2026-10-25), revision
accepted (2026-10-26) · Scope: all rn-forge-* packages and every consumer
of them
Decision
Each package has its own version and a tag named for that package and version. Packages declare each other by name and version range, with the floor at the version released against and the ceiling at the next breaking version (the next minor before 1.0). Every package is published to PyPI by trusted publishing from pykit's release workflow. A consumer requires packages by name and range with no index declaration, or pins a tag by direct URL. A published version is never replaced: a bad one is yanked and superseded by the next patch. The workspace source override serves local development. The declared requirement is the contract for an installation outside this checkout.
Before 1.0, a release with a breaking change bumps the minor and any other release bumps the patch. From 1.0, versions follow semantic versioning.
A coordinated batch records the selected packages and tag evidence on its
release page and, when that page is shipped, an umbrella GitHub release
release-<n> marked Latest.
Consequences
Versions can advance independently. A release needs actual tag and external-installability evidence; a documentation edit or a local build does not establish one. An additive release needs no release of its dependents. A breaking release needs each dependent to widen its ceiling. The release runbook describes the tagging automation and how a failed package job is handled. kiln and other libraries can depend on pykit by range, and can publish to PyPI themselves.
Influences
This decision shapes E9 release readiness, in particular F9.7, and the release pages. The workspace boundaries supply the package graph used to plan an order.
Alternatives considered
One version for the whole workspace would couple packages that have separate
dependency and release needs. Bare PyPI names could not resolve the Git-tag
distribution model of the original decision. Cutting early rn-forge-commons
and rn-forge-web tags would make outside consumers resolvable sooner, but it
releases packages before the batch scope is decided.
The 2026-10-25 revision weighed and rejected five more. Publishing to PyPI is
the simplest for consumers, but it moves where pykit lives, needs a project and
trusted publishing per package, and makes every package public on PyPI's terms.
A hosted private index (devpi, a cloud artifact registry) brings a server or an
account to keep alive for files GitHub already hosts. GitHub Packages has no
Python registry. A flat --find-links page is not a standard index, so a
consumer cannot scope it to rn-forge-*. Reserving the rn-forge-* names on
PyPI as empty placeholders guards pip users but squats a public index; the
guide's advice to use uv covers the risk.
Background
Decided by 2026-09-10; recorded here 2026-09-24. The interim rule was added 2026-09-25, when the owner chose branch pins over early tags because consumers outside the workspace could not resolve the uncut tags; the pins landed 2026-09-26.
On 2026-10-25 the owner accepted a revision: ranges against a static index on GitHub Pages replace direct-URL pins as the default, and the interim branch-pin rule, which ended at release-1, is dropped.
On 2026-10-26 the owner accepted a second revision: every package is published to PyPI, and consumers require packages by name and range with no index declaration. The GitHub Pages index is retired later.
On 2026-11-03 the self-hosted index at simple/ is retired (F21.5); packages
resolve from PyPI.