docs: add RELEASING.md

[chris-colinsky]

Summary

Final docs-phase PR. Adds RELEASING.md at the repo root, documenting the maintainer-facing release process. The release workflow (.github/workflows/release.yml) already implements the rc-first publish flow (-rc tags route to TestPyPI; plain vX.Y.Z tags route to PyPI + GitHub Release), but the human-facing process wasn't written down.

RELEASING.md covers:

• The release path — how tag names dispatch (-rc* → TestPyPI, no suffix → PyPI + GitHub Release, other suffixes are no-ops by design).
• Pre-release checklist — CHANGELOG current with the right date, docs sweep for stale references, version pin in pyproject.toml, branch state, CI green.
• Tagging the rc — concrete commands, link to watch the workflow run.
• Verifying the rc — fresh-venv install from TestPyPI (with the --extra-index-url workaround for transitive deps), 4-item smoke checklist (version string, example runs, [otel] extra installs, docs site builds).
• Tagging the real release — concrete commands, pointer to the pypi environment's required-reviewers protection rule.
• Iterating on an rc — bump the rc counter (rc2, rc3); never move the tag.
• Rollback — yank from PyPI, cut a patch; don't try to delete.
• Reference — links to release.yml, CHANGELOG.md, pyproject.toml, and the GitHub Environments.

Lives at repo root alongside CHANGELOG.md and AGENTS.md, matching the existing maintainer-doc convention. Not part of the mkdocs nav.

Test plan

• Read RELEASING.md end-to-end; the workflow it describes matches the actual .github/workflows/release.yml behavior
• Pre-release checklist matches what you actually do before tagging
• --extra-index-url line in the verification snippet is correct (standard workaround for TestPyPI not mirroring dep graphs)
• Rollback section reflects the right move for this project (yank + patch, don't try to delete)
• uv run --group docs mkdocs build --strict still succeeds (root RELEASING.md is outside docs/, so the build is unaffected)

[Copilot]

Pull request overview

Adds maintainer-facing release documentation (RELEASING.md) describing the tag-driven release flow implemented by .github/workflows/release.yml, including rc verification steps and rollback guidance.

Changes:

• Introduces RELEASING.md with an end-to-end release procedure (rc → verification → final).
• Documents tag-name dispatch rules and required environment protections (TestPyPI/PyPI environments).
• Provides concrete verification and rollback checklists for maintainers.

Comments suppressed due to low confidence (2)

RELEASING.md:50

• The pre-release checklist says to set project.version to the final target (e.g. 0.7.0) even when tagging an rc. The release workflow enforces packaging.version.Version(pyproject.version) == Version(tag_without_v), so an rc tag like v0.7.0-rc1 requires project.version to be the rc form (e.g. 0.7.0rc1 / 0.7.0-rc1). Otherwise the workflow will fail the version check (or worse: you could upload 0.7.0 to TestPyPI and then be unable to publish 0.7.0 to PyPI).

- [ ] **`pyproject.toml` version pinned.** Set `project.version` to the
      target version, e.g. `0.7.0`. The PEP 440 form (`0.7.0rc1` or
      `0.7.0`) and the tag form (`v0.7.0-rc1` or `v0.7.0`) are
      normalized to the same value, so either is accepted in the
      `pyproject` field; the tag uses the dash form for readability.

RELEASING.md:24

• This section emphasizes PEP 440 equivalence (0.7.0-rc1 ≡ 0.7.0rc1), but tag routing is not equivalent: the workflow sends tags to TestPyPI only when the tag name literally contains -rc, and sends any tag with no - to PyPI + GitHub Release. A tag like v0.7.0rc1 (no hyphen) would be treated as a real release and publish to PyPI. Consider adding an explicit warning that rc tags must use the vX.Y.Z-rcN (hyphenated) form to avoid accidental PyPI publishes.

- Tags containing `-rc` route to TestPyPI.
- Tags with no `-` suffix route to PyPI + GitHub Release.
- Any other suffix (`-beta`, `-alpha`, `-dev`, ...) is a no-op by design;
  a typo in the rc suffix cannot accidentally hit PyPI.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.