From 34851359c2de844485938ee75a028f40639ca05a Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Wed, 19 Apr 2023 15:15:22 -0400 Subject: [PATCH 1/3] Update the release process document Update the release process document with the process that we followed for the previous release. --- docs/release-process.md | 79 ++++++++++++++++++++++++++--------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index ad8a38f60..8c56f9fe8 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -1,45 +1,68 @@ -# 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. +Until NKG reaches version 1.0.0, we aim to release approximately every two months. This enables us to introduce new +features quickly while minimizing the cost of frequent releases and related procedural overhead. -Example workflow (see issue process section for more detail [TBD]): +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. -1. Discuss open features when planning. +## Releasing -1. Agree and commit to work. +Note: in the instructions below, `X` stands for the major version, `Y` -- minor, `Z` -- patch. -1. Add features to next milestone, for example, v0.2.0. +### Major or Minor Release -1. Feature "proposal" label removed and "enhancement" label added. +A Major or minor introduces new features. -### Steps to create a release. +To create a new release, follow these steps: -1. Create a release branch from main, use the naming format: release-MAJOR.MINOR. +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 + 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. -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). +### Patch Release -3. Test the release candidate. +A patch release is for an important fix that cannot wait the next major/minor release. - If the tests fail +To create a new release, follow these steps: - - 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. From 0b7c9996844433f2efe5a5f4bcd252279ff95924 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Wed, 19 Apr 2023 18:57:03 -0400 Subject: [PATCH 2/3] Remove release cadence --- docs/release-process.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index 8c56f9fe8..42095d3ea 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -10,9 +10,6 @@ NKG uses semantic versioning for its releases. For more information, see https:/ ## Release Planning and Development -Until NKG reaches version 1.0.0, we aim to release approximately every two months. This enables us to introduce new -features quickly while minimizing the cost of frequent releases and related procedural overhead. - 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. From 224ba6dfa2519b6148b0458188d4a1cbdb3a5dd0 Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Fri, 21 Apr 2023 13:35:31 -0400 Subject: [PATCH 3/3] Collapse changelog step into repo files step --- docs/release-process.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index 42095d3ea..7c9b69f7f 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -37,15 +37,15 @@ To create a new release, follow these steps: 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 - 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: + 6. Update the [changelog](../CHANGELOG.md). The changelog includes only important (from the 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. +7. 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 +8. 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. +9. Close the issue created in Step 1. ### Patch Release @@ -62,4 +62,4 @@ To create a new release, follow these steps: 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. +6. Follow Steps 6-9 from the [Major or Minor Release](#major-or-minor-release) section.