Skip to content

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, and latest names the newest release. A package's metadata and README link to latest.
  • 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.md follows Keep a Changelog, appears in the package site, and is linked from the package metadata as Changelog. [project.urls] also names Documentation, Source and Issues.

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.