Skip to content

RELEASE.md

Latest commit

聽

History

History
135 lines (107 loc) 路 6.46 KB

RELEASE.md

File metadata and controls

135 lines (107 loc) 路 6.46 KB
Raw

Higress Release Process

This document defines the project-wide process for producing a Higress core release from the primary repository. Subprojects may add repository-specific steps, but must use the same public approval and security principles.

Versioning and support

Higress uses Semantic Versioning with Git tags in the form vMAJOR.MINOR.PATCH. A release-candidate tag may add an -rc.N suffix.

  • A major release may contain incompatible changes and requires migration guidance.
  • A minor release adds backward-compatible features and may contain announced deprecations.
  • A patch release contains backward-compatible fixes, including security fixes when appropriate.

The supported major-version lines are listed in SECURITY.md. A proposal to end support for a major line is made publicly through a pull request updating SECURITY.md, normally at least 90 days before the stated end of support. Already unsupported versions do not receive routine fixes.

Roles and authorization

A maintainer acts as release manager for each release. The release manager coordinates the tracking issue, version changes, validation, tag, automation, and announcement. At least one other unconflicted maintainer reviews and approves the release pull request. Only maintainers with the required GitHub and protected-environment access may create release tags or approve publishing jobs.

Security releases additionally follow SECURITY.md. Embargoed details stay in the private advisory until the Security Response Team approves disclosure.

1. Plan the release

The release manager opens or identifies a public tracking issue for a normal release. It records:

  • the target version and release type;
  • intended scope and linked changes;
  • the release manager and expected timing;
  • known compatibility, migration, deprecation, and security considerations;
  • validation status and unresolved blockers.

An embargoed security release uses a private advisory for planning until public disclosure is safe.

2. Prepare the release pull request

For a release carrying managed Go/Rust plugin defaults, complete the code freeze, plugin snapshot/plugin-server, and Console release prerequisites below before creating the release pull request. Then create that pull request against main, keeping the version in VERSION, helm/core/Chart.yaml, helm/higress/Chart.yaml, dependency metadata, and release notes consistent. Update documentation, migration or deprecation guidance, and supported-version information when they change.

First freeze an exact main/code-freeze commit at the current main head and use it to prepare and merge the generated plugin snapshot PR. Promote that snapshot, build plugin-server, then merge/release the generated Console dependency. Only after those inputs converge should the release manager create or update a #4019-style release PR on main. Limit it to release metadata, Helm dependency, release notes, and intended submodule pins. Do not manually edit managed plugin VERSION files in this PR. Update the Console dependency and run helm dependency update helm/higress to regenerate Chart.lock; review the resulting Chart.yaml and Chart.lock. If the release PR changes a catalog-declared plugin artifact input, stop and reprepare the snapshot/plugin-server/Console chain from the new exact main commit. Merge the release PR only immediately before dispatching exact tag authorization with the approved dry-run evidence SHA-256.

The pull request must pass the repository's required build, unit, race, conformance, plugin, license, and other configured checks relevant to its changes. The release manager records any intentionally inapplicable check or accepted exception in the pull request. A known release-blocking regression, unresolved critical vulnerability, inconsistent version, or missing migration guidance blocks the release.

The approving maintainer verifies that the release scope matches the public plan, required checks passed, versioned dependencies are intentional, and the release notes accurately describe user-visible changes.

3. Tag and publish

After the release pull request is merged, the release manager creates the corresponding immutable vMAJOR.MINOR.PATCH or release-candidate tag from the reviewed commit. Published tags are not moved or reused. For releases carrying managed Go/Rust Wasm defaults, the manager must first complete the exact-commit readiness gate described in docs/developers/immutable-plugin-releases.md: the committed snapshot, promoted plugin digests, pinned plugin-server image, and released Console chart dependency must all verify before the protected release-manager App creates the tag.

The tag triggers GitHub Actions that publish, as applicable:

  • controller, pilot, and gateway container images;
  • Helm charts and chart indexes;
  • hgctl archives for supported platforms;
  • generated CRDs;
  • standalone distribution artifacts;
  • GitHub release notes and repository release notes.

Manual workflow dispatch is for recovery or a documented exceptional case; it does not bypass release approval or change the commit being released.

4. Verify and announce

The release manager verifies that publishing workflows succeeded and that the release page, checksums or archives, image tags, Helm charts, CRDs, and release notes refer to the intended version. Installation and representative gateway traffic are smoke-tested with the published artifacts before the release is announced as ready.

Release announcements link the GitHub release and call out breaking changes, deprecations, migrations, known issues, and security impact. Confirmed security issues are disclosed through a GitHub Security Advisory and CVE when appropriate.

Failure, rollback, and correction

If validation or publishing fails, stop promotion and document the failure in the tracking issue or release pull request. Do not move or overwrite an existing public tag. Fix the problem through normal review and publish a new release-candidate or patch version.

An operator rollback uses the previously pinned Helm chart, configuration, and images, normally through helm rollback. Because CRD schemas and stored resources may not be reversible, release notes must identify migrations that need special rollback handling. The project may withdraw a compromised artifact from distribution, but it preserves a public advisory and audit trail explaining the affected version and safe replacement.