F9.9 — Publish each package's documentation
| State | Closed |
| Parent | E9 |
| Iteration | Release 1 |
| Closed Date | 2026-09-26 |
| Predecessors | ADR-0009; before S9.6.1 |
| Source | Owner decision, 2026-09-26, recorded in ADR-0009 |
Stories: 4 Closed
| Story | State | Depends on |
|---|---|---|
| S9.9.1 — Record the decision | Closed (2026-09-26) | — |
| S9.9.2 — Package metadata and landing READMEs | Closed (2026-09-26) | — |
| S9.9.3 — A changelog per package | Closed (2026-09-26) | — |
| S9.9.4 — Deploy versioned package sites | Closed (2026-09-26) | — |
Outcome: each package publishes a versioned site, a changelog and a landing README (Release 5, 2026-09-26), per ADR-0009. The need was documentation matching the version a user pinned.
Context
S9.9.4 had to land before the tag cut (S9.6.1), because release-1's package metadata links to the versioned sites it publishes.
Design
The versioned sites are deployed by the docs job with mike, whose approval
as a dependency the owner gave on 2026-09-26. Two reasons shaped the job.
Package jobs push tags with GITHUB_TOKEN, which starts no workflow run, so a
tag-triggered workflow would never fire; the docs job instead deploys the
packages whose tags point at the pushed commit. And all mike pushes run one
after another in that single job, so parallel package jobs never race on
gh-pages. Tags cut before this feature were not backfilled. The deployed
layout is described in ADR-0009 and the
release runbook.
S9.9.1 — Record the decision
State: Closed (2026-09-26)
Acceptance: ADR-0009 is accepted and listed in the decision index.
S9.9.2 — Package metadata and landing READMEs
State: Closed (2026-09-26)
Acceptance: every package's [project.urls] names Documentation (its
latest site), Source, Changelog and Issues. Every link in a package
README is absolute, and each README opens with links to the documentation,
changelog, source and root site. Every package mkdocs.yml sets site_url and
repo_url.
S9.9.3 — A changelog per package
State: Closed (2026-09-26)
Acceptance: every package has a CHANGELOG.md in Keep a Changelog form. Its
docs/changelog.md includes the file through pymdownx.snippets and is in the
package nav, and the root and package sites render it under --strict.
S9.9.4 — Deploy versioned package sites
State: Closed (2026-09-26)
Acceptance: on a push to main that creates a package tag, CI deploys that
package's site to
https://rn-forge.github.io/pykit/packages/<package>/<major>.<minor>/ and
points latest at it, and the root site stays at
https://rn-forge.github.io/pykit/. After release-1's tag cut, all seven
packages' latest pages and the root page load.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
test -f docs/adr/ADR-0009.md # S9.9.1
grep -q 'ADR-0009.md' docs/adr/index.md # S9.9.1
for pkg in packages/rn-forge-*; do
for key in Documentation Source Changelog Issues; do # S9.9.2
grep -q "^$key = \"https://" "$pkg/pyproject.toml"
done
grep -q '^site_url: https://' "$pkg/mkdocs.yml" # S9.9.2
grep -q '^repo_url: https://' "$pkg/mkdocs.yml" # S9.9.2
test -f "$pkg/CHANGELOG.md" # S9.9.3
grep -q 'Changelog: changelog.md' "$pkg/mkdocs.yml" # S9.9.3
(cd "$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S9.9.3
done
absent --pcre2 '\]\((?!https?://|#)' packages/rn-forge-*/README.md # S9.9.2
uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)" # S9.9.3
for pkg in commons cli tooling web django fastapi sqlalchemy; do # S9.9.4, after S9.6.1
curl -fsS -o /dev/null "https://rn-forge.github.io/pykit/packages/rn-forge-$pkg/latest/index.html"
done
curl -fsS -o /dev/null https://rn-forge.github.io/pykit/index.html # S9.9.4