Skip to content

Latest commit

 

History

History
168 lines (119 loc) · 5.51 KB

RELEASE.md

File metadata and controls

168 lines (119 loc) · 5.51 KB

Release

The Prometheus Go client library does not follow a strict release schedule. Releases are made based on necessity and the current state of the project.

Branch Management

We use Semantic Versioning.

  • Maintain separate release-<major>.<minor> branches
  • Branch protection enabled automatically for release-* branches
  • Bug fixes go to the latest release branch, then merge to main
  • Features and changes go to main branch
  • Non-latest minor release branches are maintained (e.g. bug and security fixes) on the best-effort basis

Pre-Release Preparations

  1. Review main branch state:
    • Expedite critical bug fixes
    • Don't rush on risky changes, consider them for the next release if not ready
    • Update dependencies via Dependabot PRs or manually if needed
    • Check for security alerts

Cutting a Minor Release

  1. Create release branch:

    git checkout -b release-<major>.<minor> main
git push origin release-<major>.<minor>

  2. Create a new branch on top of release-<major>.<minor>:

    git checkout -b <yourname>/cut-<major>.<minor>.0 release-<major>.<minor>

  3. Update version and documentation:

    • Update VERSION file
    • Update CHANGELOG.md (user-impacting changes)
      • Each release documents the minimum required Go version
    • Order: [SECURITY], [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]
    • For RCs, append -rc.0

  4. Create PR and get review

  5. After merge, create tags:

    tag="v$(< VERSION)"
git tag -s "${tag}" -m "${tag}"
git push origin "${tag}"

  6. Create a draft release.

  • Copy Changelog section.
  • You can also generate automatic changelog and put the What's changed section under <summary> HTML tag. This will render all contributors nicely as in the example release.

7a. For Release Candidates:

  • Release RC GitHub release with "pre-release" box checked
  • Click "Publish release"!
  • Create PR against prometheus/prometheus using RC version
  • Create PR against kubernetes/kubernetes using RC version
  • Make sure the CI is green for the PRs
  • Allow 1-2 days for downstream testing
  • Fix any issues found before final release
  • Use -rc.1, -rc.2 etc. for additional fixes

7b. For Final Release:

  • Release GitHub release with "latest" box checked (default).
  • Click "Publish release"!

  1. Announce release:

  2. Merge release branch to main:

    git checkout main
git merge --no-ff release-<major>.<minor>

Cutting a Patch Release

  1. Create branch from release branch:

    git checkout -b <yourname>/cut-<major>.<minor>.<patch> release-<major>.<minor>

  2. Apply fixes:

    • Commit the required fixes; avoid refactoring or otherwise risky changes (preferred)
    • Cherry-pick from main if fix was already merged there: git cherry-pick <commit>

  3. Follow steps 3-9 from minor release process

Handling Merge Conflicts

If conflicts occur merging to main:

  1. Create branch: <yourname>/resolve-conflicts
  2. Fix conflicts there
  3. PR into main
  4. Leave release branch unchanged

Note on Versioning

Compatibility Guarantees

Supported Go Versions

  • Support provided only for the three most recent major Go releases
  • While the library may work with older Go versions, support and fixes are best-effort for those.
  • Each release documents the minimum required Go version

API Stability

The Prometheus Go client library aims to maintain backward compatibility within minor versions, similar to Go 1 compatibility promises:

Minor Version Changes

  • API signatures are stable within a minor version
  • No breaking changes are introduced
  • Methods may be added, but not removed
    • Arguments may NOT be removed or added (unless varargs)
    • Return types may NOT be changed
  • Types may be modified or relocated
  • Default behaviors might be altered (unfortunately, this has happened in the past)

Major Version Changes

  • API signatures may change between major versions
  • Types may be modified or relocated
  • Default behaviors might be altered
  • Feature removal/deprecation can occur with minor version bump

Compatibility Testing

Before each release:

  1. Internal Testing:

    • Full test suite must pass
    • Integration tests with latest Prometheus server
    • (optional) Benchmark comparisons with previous version

    There is no facility for running benchmarks in CI, so this is best-effort.

  2. External Validation:

Test against bigger users, especially looking for broken tests or builds. This will give us awareness of a potential accidental breaking changes, or if there were intentional ones, the potential damage radius of them.

Version Policy

  • Bug fixes increment patch version (e.g., v0.9.1)
  • New features increment minor version (e.g., v0.10.0)
  • Breaking changes increment minor version with clear documentation

Deprecation Policy

  1. Features may be deprecated in any minor release
  2. Deprecated features:
    • Will be documented in CHANGELOG.md
    • Will emit warnings when used (when possible)