Skip to content

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