Skip to content

releasing.md

Latest commit

 

History

History
50 lines (37 loc) · 2.49 KB

releasing.md

File metadata and controls

50 lines (37 loc) · 2.49 KB
Raw

Releasing

Policy

Patch bumps are cheap. Prefer frequent small releases over feature-batching. Contract changes (§10.1/§10.2/§10.3 — see contracts.md) are the one exception: they demand a deliberate ceremony.

Versioning follows Semantic Versioning:

  • Patch — bug fixes, doc clarifications, additive internal refactors.
  • Minor — new features, additive contract changes (new CSL field, new policy, schema_version additive).
  • Major — contract breaks (renamed/removed CSL field, renamed GenerationResult field, changed citation marker shape, dropped policy).

The release flow

  1. Land all PRs for the release into main.
  2. Run /bump [patch|minor|major] (or invoke the release-bump skill) — updates src/citeformer/_version.py and moves [Unreleased] into a numbered CHANGELOG.md entry.
  3. Commit, push, open a "release vX.Y.Z" PR. Merge after CI is green.
  4. Tag on main: git tag vX.Y.Z && git push --tags.
  5. GitHub Actions release.yml picks up the tag, builds sdist + wheel, publishes to PyPI via OIDC trusted publishing, and attaches artifacts to a GitHub Release with a CHANGELOG-link note.

Pre-release checklist

Before pushing the tag:

  • make lint && make test && make docs-build all green locally
  • CI green on main
  • CHANGELOG.md has the new version section (not [Unreleased])
  • /contract-check clean if any §10 files were touched
  • src/citeformer/_version.py matches the tag
  • Any new deps reflected in the right pyproject.toml extra

ReadTheDocs — one-time import

The .readthedocs.yaml in the repo root is wired up; what's left is the one-time import on readthedocs.org.

  1. Sign in at https://app.readthedocs.org/ with the GitHub account that owns random-walks/citeformer.
  2. Import a project → import manually (or use the GitHub integration if random-walks is connected).
    • Repository URL: https://github.com/random-walks/citeformer
    • Default branch: main
    • Documentation type: Sphinx
  3. After the first build succeeds, enable the Automation rule that activates new tags (so v0.1.1, v0.1.2, … appear under the version picker without manual intervention).
  4. Confirm the URL resolves: https://citeformer.readthedocs.io/en/latest/.

Once live, the RTD badge in the README (which currently points at an unimported slug) will start rendering the real build status.