Release and Versioning

PatchPatrol operators use SemVer release artifacts aligned across three files and tags.

Source of truth

The release contract is documented in:

• pyproject.toml ([project].version, e.g. 1.3.0)
• CHANGELOG.md (## [X.Y.Z] - YYYY-MM-DD)
• Git tag form vX.Y.Z
• docs/policies/release-versioning.md

All three must match at release time.

Historical repository tags v1.0, v1.1, v1.2, and v1.3 are milestone archive markers, not SemVer product releases. Production-style pinning starts with three-part release tags such as v1.3.0.

What to expect in a release

• Public source release notes are tracked in CHANGELOG.md.
• Versioning follows MAJOR.MINOR.PATCH:
  • MAJOR: breaking change to documented behavior or compatibility.
  • MINOR: backward-compatible additions.
  • PATCH: fixes and docs-only improvements.
• Registry image names are:
  • registry.patchpatrol.ai/patchpatrol
  • registry.patchpatrol.ai/patchpatrol-semantic

Most clients should use latest in CI. Use vX.Y.Z only when you need to stay on a specific patch version. Patch tags such as vX.Y.Z remain immutable. Authentication is required before pulling images.

Public release entrypoint links

Use these links when communicating support and upgrade decisions:

• Release policy: docs/policies/release-versioning.md
• Changelog: CHANGELOG.md
• Security and support posture: SECURITY.md, docs/policies/support-policy.md

Practical upgrade flow

1. Confirm the target version in policy and changelog.
2. Keep latest in the review job if you want automatic uptake of review improvements.
3. If you need a specific patch version, update the review job tag to vX.Y.Z.
4. Run readiness checks and one artifact-first GitLab merge request path before wider rollout.

Notes for operators

• latest is the recommended default when you want the most recent review improvements.
• Rollback is handled by selecting the required vX.Y.Z image tag and re-validating the same job path.
• If an upgrade requires changing provider endpoints or model behavior, run a full onboarding verification again after the version change.

Next step

If you are moving from trial setup to regular usage, start with:

• Installation and upgrades
• Troubleshooting