release-bump

name	release-bump
description	Use this rubric when deciding between patch, minor, and major version bumps for citeformer. Patch bumps are cheap — prefer frequent small releases over feature-batching.

Release bump rubric

citeformer versions follow Semantic Versioning, with patch bumps preferred over feature-batching.

Patch — bug fixes, docs, internal refactors

Pick patch if:

• You fixed a bug without changing the public API.
• You clarified documentation, typos, or examples.
• You refactored internals with no user-visible effect.
• You pinned a dependency tighter (e.g. torch>=2.4 → torch>=2.5) for a compatibility reason.
• You updated CI, build, or tooling configs.

Minor — new features or additive contract changes

Pick minor if:

• You added a new public function, class, backend, policy, CSL style, or metadata adapter.
• You added a new optional parameter to an existing function.
• You added a new optional dependency extra.
• You added a new field to Source.metadata passthrough (§10.2 additive).
• You added a new policy (§10.1 additive — e.g. numeric_only alongside required/quotes_only/auto).
• You added a new field to GenerationResult or VerificationReport without bumping schema_version (§10.3 additive; fields are non-breaking because existing consumers ignore them).

Major — §10 contract break

Pick major if any of the three §10 contracts is broken (not additive):

• §10.1 — the cite-id rule shape changes; the semantics of an existing policy change; a policy is removed.
• §10.2 — a field is renamed or removed from the Source.metadata expected shape.
• §10.3 — a field is renamed or removed from GenerationResult or VerificationReport; schema_version must be bumped (1 → 2).

Major bumps must include:

• A schema_version bump on the affected model (§10.3 only).
• A CHANGELOG Contracts (§10) section describing the break and the migration path.
• contracts:breaking PR label if the CI enforces it.

When in doubt

• Unsure whether a change is additive or breaking? Run /contract-check. The agent will classify and tell you the recommended bump.
• Unsure whether a fix is a bug or a behavior change? If it changes observable output for any valid input, it's at least minor. If it changes the shape of the output, it's probably major.

Cadence

Target 1–2 patch releases per week while the repo is under active development. Minor releases land when a phase completes (P1, P2, …) or when a coherent feature batch is ready. Major releases are rare by construction — they only come from contract breaks.