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. 0.1.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.

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.
• GHCR image names are:
  • ghcr.io/aistack-projects/patchpatrol
  • ghcr.io/aistack-projects/patchpatrol-semantic

For production-like environments, use immutable tags (for example vX.Y.Z) in CI.

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. Update the pinned image tag used by your review job to vX.Y.Z.
3. Run readiness checks and one artifact-first GitLab merge request path before wider rollout.
4. Keep version pinning explicit and documented in deployment configuration.

Notes for operators

• Avoid broad "latest" semantics for long-lived environments.
• Rollback is handled by selecting the previous immutable 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