ADR-0009: Each package publishes its own versioned docs; the root site browses them all
Status: accepted (2026-09-26) · Scope: package documentation, package metadata and the docs deployment
Decision
pykit's documentation serves two readers: someone browsing the workspace, and someone using one installed package.
- The package site is the package's documentation of record. Each package's
standalone site is published at
https://rn-forge.github.io/pykit/packages/<package>/<major>.<minor>/, built from that package's release tag, andlatestnames the newest release. A package's metadata and README link tolatest. - The root site browses everything, built from
main. It keeps including every package site and all cross-package material. It reflects the branch it was built from and makes no claim about any released version. - The README is the package's landing page on any index. Every link in it is absolute, and it opens with links to the documentation, changelog, source and the root site.
- Each package has a changelog.
packages/<package>/CHANGELOG.mdfollows Keep a Changelog, appears in the package site, and is linked from the package metadata asChangelog.[project.urls]also namesDocumentation,SourceandIssues.
Every package keeps the same docs shape (ADR-0007), so a package's docs work in both sites unchanged. This does not choose a package index: the metadata and README work on any index, and pinned git tags stay the distribution contract (ADR-0004).
Consequences
A user who arrives from an index page, or from pip show, reaches docs that
match the version they pinned. A maintainer still has one site that covers the
whole workspace. Each page exists at two addresses, the versioned copy and the
root site's copy from main, and only the versioned copy speaks for a release.
Publishing old versions needs storage the Pages deployment keeps between runs,
which F9.9 designs.
Each release needs a changelog entry before its tag is cut.
Influences
This decision shapes F9.9, the release runbook and the adding-a-package runbook. Under ADR-0007 it is also a proposed change to the shared docs standard.
Alternatives considered
- The root site only. It is simpler, but it documents
main, while packages are pinned by version. A user of an older release would read the wrong contract, and index pages would link into governance pages they have no use for. - Package sites only, with a link portal at the root. This gives each page one canonical address, but the owner wants the whole workspace browsable in one site, with its search and nav.
- Read the Docs, with one project per package. It versions each package natively, but it adds a host where GitHub Pages already serves the root site.
Background
Decided by the owner on 2026-09-26: packages will eventually be published to a package index, so package-level docs must be reachable from there, while the root site stays browsable across every package from the branch it was built from.