Skip to content

docs: release runbook for the multi-distribution layout - #153

Merged
cayossarian merged 1 commit into
developfrom
docs/release-runbook
Aug 4, 2026
Merged

docs: release runbook for the multi-distribution layout#153
cayossarian merged 1 commit into
developfrom
docs/release-runbook

Conversation

@cayossarian

Copy link
Copy Markdown
Member

Adds RELEASE.md. Nothing recorded how releasing works now that this repo
publishes two PyPI distributions from one source tree, so every release meant
re-deriving it from release.yml.

What it covers

  • Layout — which distribution lives where, and the three consequences for
    releasing (own version, own PyPI project, one release publishes one package).
  • Why two version axes — the bootstrap versions on its library API, an
    adapter on its library API with the wire format declared by
    SUPPORTS_DATA_MODEL_VERSIONS rather than the version number.
  • Tag → distribution → manifest, including the worked parameter-expansion
    example, and why schema-1-v0.1.0 will resolve with no workflow edit.
  • Why the tag verifies rather than sets the version, and that the ritual is
    bump-commit-then-tag.
  • Releasing one distribution and releasing the whole workspace — the
    latter being the "how does an admin release everything" answer: a sequence of
    single releases, bootstrap first, with the dependency-floor caveat.
  • Adding a new adapter — the PyPI pending-publisher table, which is the step
    most likely to be forgotten when schema-1 lands.
  • Failure-message table, each string checked against the workflow.
  • Verifying from PyPI, since CI going green proves the build and not the
    install — the entry-point seam only exists across a real package boundary.
  • Pre-releases--pre on PyPI, the checkbox on GitHub, and that the
    workflow is indifferent.

Also

  • DEVELOPMENT.md gains a workspace-layout section and a pointer to the runbook.
  • README install instructions fixed. They still read
    pip install span-panel-api alone, which on this branch gives a client with
    no parser that connects and then raises SpanPanelAdapterMissingError.

Known remaining doc staleness (not addressed here)

The README's Architecture section still describes HomiePropertyAccumulator
and HomieLifecycle as part of this package. They moved to
span_panel_api_schema_0 in Phase 1 and are no longer exported, which the
changelog records but the README contradicts. That is a substantive rewrite of
a section rather than a correction, so it is called out rather than folded in.

The repository publishes more than one PyPI distribution from one source tree,
and nothing recorded how that works. Every release would have meant
re-deriving it from the workflow.

RELEASE.md covers the layout, why the bootstrap and adapters version on
separate axes, how a tag selects a distribution and its manifest, the
single-distribution and whole-workspace procedures, what has to be set up on
PyPI before a new adapter's first release, what each failure message means, and
how to verify a release from PyPI rather than from CI.

Also fixes the README's install instructions, which still said
`pip install span-panel-api` alone. On this branch that produces a client with
no parser that connects and then raises SpanPanelAdapterMissingError.
@cayossarian
cayossarian merged commit efc11d7 into develop Aug 4, 2026
5 checks passed
@cayossarian
cayossarian deleted the docs/release-runbook branch August 4, 2026 22:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant