Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the release process document #585

Merged
merged 4 commits into from
Apr 21, 2023
Merged

Update the release process document #585

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3485135
Update the release process document
pleshakov Apr 19, 2023
0b7c999
Remove release cadence
pleshakov Apr 19, 2023
224ba6d
Collapse changelog step into repo files step
pleshakov Apr 21, 2023
3df3985
Merge branch 'main' into chore/release-process
pleshakov Apr 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 49 additions & 29 deletions docs/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,65 @@
# Releases
# Release Process

NGINX Kubernetes Gateway uses semantic versioning for its releases. For more information see https://semver.org.
This document outlines the release process for NGINX Kubernetes Gateway (NKG).

Warning: Major version zero (0.y.z) is reserved for development, anything MAY change at any time. The public API is not stable.
## Versioning

NGINX Kubernetes Gateway, especially in its early stages, will release periodically on a feature set cadence. By feature set, we intend to mean 2-4 features as tracked by the repository's Github milestones. We do this to remain agile and to expose features relatively quickly, but also to minimize the cost of many frequent releases and the associated process overhead.
NKG uses semantic versioning for its releases. For more information, see https://semver.org.

This means users can expect a release generally every 1 or 2 months, and can also track the progress of a release and its features by viewing our Github milestones. Each issue scheduled for a release will be labelled with "enhancement" (initial feature requests are "proposals", the label "enhancement" will be exchanged when work is committed) and added to the milestone release, milestones will use the form vMAJOR.MINOR.PATCH. Multiple issues may be written to describe one use-case and each will be organized according to this process. Sub-issues should also link to their parent (the parent issue will list the links via mention notifications).
> Major version zero `(0.Y.Z)` is reserved for development, anything MAY change at any time. The public API is not stable.

Bugs and other issue types will use a similar format; once committed to a release they will be assigned to the milestone representing that release.
## Release Planning and Development

When all milestone work is complete, we will begin our release process and publish artifacts accordingly.
The features that will go into the next release are reflected in the
corresponding [milestone](https://github.com/nginxinc/nginx-kubernetes-gateway/milestones). Refer to
the [Issue Lifecycle](../ISSUE_LIFECYCLE.md) document for information on issues creation and assignment to releases.

Example workflow (see issue process section for more detail [TBD]):
## Releasing

1. Discuss open features when planning.
Note: in the instructions below, `X` stands for the major version, `Y` -- minor, `Z` -- patch.

1. Agree and commit to work.
### Major or Minor Release

1. Add features to next milestone, for example, v0.2.0.
A Major or minor introduces new features.

1. Feature "proposal" label removed and "enhancement" label added.
To create a new release, follow these steps:

### Steps to create a release.
1. Create an issue to define and track release-related activities. Choose a title that follows the
format `Release X.Y.Z`.
2. Stop merging any new work into the main branch.
3. Test the main branch for release-readiness. For that, use the `edge` containers, which are built from the main
branch.
4. If a problem is found, prepare a fix PR, merge it into the main branch and return to the previous step.
5. Create a release branch with a name that follows the `release-X.Y` format.
6. Prepare and merge a PR into the release branch to update the repo files for the release:
1. Update the tag of NKG container images used in the installation manifests and docs to `X.Y.Z`.
2. Ensure that the `imagePullPolicy` is `IfNotPresent` in the installation manifests.
3. Modify any `git clone` instructions to use `vX.Y.Z` tag.
4. Adjust the `VERSION` variable in the [Makefile](../Makefile) to `X.Y.Z`.
5. Update the [README](../README.md) to include information about the release.
7. Prepare and merge a PR to update the [changelog](../CHANGELOG.md). The changelog includes only important (from the
pleshakov marked this conversation as resolved.
Show resolved Hide resolved
user perspective) changes to NKG. This is in contrast with the autogenerated full changelog, which is created in the
next step. Use the previous changelog entries for formatting and content guidance.
8. Create and push the release tag in the format `vX.Y.Z`. As a result, the CI/CD pipeline will:
* Build NKG container images with the release tag `X.Y.Z` and push it to the registry.
* Create a GitHub release with an autogenerated changelog and attached release artifacts.
9. Prepare and merge a PR into the main branch to update the [README](../README.md) to include the information about the
latest release and also the [changelog](../CHANGELOG.md).
10. Close the issue created in Step 1.

1. Create a release branch from main, use the naming format: release-MAJOR.MINOR.
### Patch Release

2. Create a release candidate tag, use the naming format: vMAJOR.MINOR.PATCH-rc.N (N must start from 1 and monotonically increase with each release candidate).
A patch release is for an important fix that cannot wait the next major/minor release.

3. Test the release candidate.
To create a new release, follow these steps:

If the tests fail

- Create a fix for the error.

- Open a PR with the fix against the main branch.

- Once approved and merged, cherry-pick the commit into the release branch.

- Create a new release candidate tag, increment the release candidate number by 1.

4. Iterate over the process in step 3 until all the tests pass on the release candidate tag then create the final release tag from the release branch in the format vMAJOR.MINOR.PATCH. The docker image will automatically be pushed to ghcr.io/nginxinc/nginx-kubernetes-gateway:MAJOR.MINOR.PATCH with the release tag as the docker tag.

5. Update the changelog with the changes added in the release. They can be found in the github release notes that was generated from the release branch.
1. Create an issue to define and track release-related activities. Choose a title that follows the
format `Release X.Y.Z`.
2. If the fix applies to both the latest release and the main branch, then:
1. Prepare and merge a fix PR into the in the main branch.
2. Prepare and merge a fix PR (with a cherry-pick commit) into the existing release branch.
3. Alternatively, if the fix only applies to the latest release, prepare and merge a fix PR into the existing release
branch.
4. Test the release branch for release-readiness.
5. If a problem is found, return to Step 2.
6. Follow Steps 6-10 from the [Major or Minor Release](#major-or-minor-release) section.