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.

GitLab component versioning

The GitLab CI/CD component has its own Catalog version. Component tags use plain SemVer without the product v prefix:

include:
  - component: $CI_SERVER_FQDN/patchpatrol/components/gitlab-review@1.0.0

Keep the component include pinned to a trusted SemVer tag. PatchPatrol runtime image tags keep the vX.Y.Z form and are configured separately through the component image input only when you need a frozen runtime:

include:
  - component: $CI_SERVER_FQDN/patchpatrol/components/gitlab-review@1.0.0
    inputs:
      image: registry.patchpatrol.ai/patchpatrol:v1.3.0

Most teams upgrade by changing the component tag first, running one artifact-first merge request pipeline, and only then enabling broader rollout. Rollback is the inverse: pin the component include back to the last known-good SemVer tag and rerun the same artifact-first path.

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 use the GitLab component, update the component tag such as gitlab-review@1.0.0.
4. If you need a specific runtime patch version, update the image tag to vX.Y.Z.
5. 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