diff --git a/README.md b/README.md index 548c31434..52e0190f0 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,35 @@ You can reach the maintainers of this project at: Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). -## Releases - -To reduce version-skew risk, it is recommended to match apiserver-network-proxy server & client +## Versioning and releases + +As of the `0.28.0` release, the apiserver-network-proxy project is changing its versioning and release +process. Going forward the project will adhere to these rules: + +* This project follows semantic versioning (eg `x.y.z`) for releases and tags. +* Tags indicate readiness for a release, and project maintainers will create corresponding releases. +* Releases and tags align with the Kubernetes minor release versions (the `y` in `x.y.z`). For instance, + if Kubernetes releases version `1.99.0`, the corresponding release and tag for apiserver-network-proxy will be + `0.99.0`. +* Branches will be created when the minor release version (the `y` in `x.y.z`) is increased, and follow the + pattern of `release-x.y`. For instance, if version `0.99.0` has been released, the corresponding branch + will be named `release-0.99`. +* Patch level versions for releases and tags will be updated when patches are applied to the specific release + branch. For example, if patches must be applied to the `release-0.99` branch and a new release is created, + the version will be `0.99.1`. In this manner the patch level version number (the `z` in `x.y.z`) may not + match the Kubernetes patch level. + +For Kubernetes version `1.28.0+`, we recommend using the tag that corresponds to the same minor version +number. For example, if you are working with Kubernetes version `1.99`, please utilize the latest `0.99` +tag and refer to the `release-0.99` branch. It is important to note that there may be disparities in the +patch level between apiserver-network-proxy and Kubernetes. + +For Kubernetes version `<=1.27`, it is recommended to match apiserver-network-proxy server & client minor release versions. With Kubernetes, this means: -- Kubernetes v1.27+: `0.1.X` tags, `master` branch -- Kubernetes versions v1.23 to v1.27: `0.0.X` tags, `release-0.0` branch -- Kubernetes versions up to v1.23: apiserver-network-proxy versions up to `v0.0.30`. +* Kubernetes versions v1.26 through v1.27: `0.1.X` tags, `release-0.1` branch. +* Kubernetes versions v1.23 through v1.25: `0.0.X` tags, `release-0.0` branch. +* Kubernetes versions up to v1.23: apiserver-network-proxy versions up to `v0.0.30`. Refer to the kubernetes go.mod file for the specific release version. ## Build diff --git a/RELEASE.md b/RELEASE.md index 230485e63..3b0c31c48 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -4,9 +4,9 @@ Please note this guide is only intended for the admins of this repository, and r Creating a new release of network proxy involves releasing a new version of the client library (konnectivity-client) and new images for the proxy agent and server. Generally we also want to upgrade kubernetes/kubernetes with the latest version of the images and library, but this is a GCE specific change. -1. The first step involves creating a new git tag for the release, following semver for go libraries. A tag is required for both the repository and the konnectivity-client library. For example releasing the `0.0.15` version will have two tags `v0.0.15` and `konnectivity-client/v0.0.15` on the appropriate commit. +1. The first step involves creating a new git tag for the release, following semver for go libraries. A tag is required for both the repository and the konnectivity-client library. For example releasing the `0.99.0` version will have two tags `v0.99.0` and `konnectivity-client/v0.99.0` on the appropriate commit. The minor version number (the `y` in `x.y.z`) should match the minor version of the Kubernetes version that is utilized by the apiserver-network-proxy. The patch level version number (the `z` in `x.y.z`) should increase by one unless a new minor version is being created, in which case it should be `0`. - In the master branch, choose the appropriate commit, and determine a patch version for the latest minor version (currently 0.1). + In the master branch, choose the appropriate commit, and determine a patch version based on the required Kubernetes version and the current patch level. Example commands for `HEAD` of `master` branch. (Assumes you have `git remote add upstream git@github.com:kubernetes-sigs/apiserver-network-proxy.git`.) @@ -40,7 +40,18 @@ Creating a new release of network proxy involves releasing a new version of the Once the two tags are created, the konnectivity-client can be imported as a library in kubernetes/kubernetes and other go programs. -2. To publish the proxy server and proxy agent images, they must be promoted from the k8s staging repo. An example PR can be seen here: [https://github.com/kubernetes/k8s.io/pull/1602](https://github.com/kubernetes/k8s.io/pull/1602) +2. If increasing the minor version (the `y` in `x.y.z`), a new release branch must be created. The name of this branch should be `release-x.y` where `x` and `y` correspond to the major and minor release numbers for apiserver-network-proxy. For example, if increasing the apiserver-network-proxy from verision `0.98.4` to `0.99.0` a new branch should be created named `release-0.99`. + + After making the new tag for the release version, use the following command to create the new branch: + + ``` + # assuming a release version of 0.99.0 + export RELEASE=release-0.99 + git checkout -b "${RELEASE}" + git push upstream "${RELEASE}" + ``` + +3. To publish the proxy server and proxy agent images, they must be promoted from the k8s staging repo. An example PR can be seen here: [https://github.com/kubernetes/k8s.io/pull/5686](https://github.com/kubernetes/k8s.io/pull/5686) The SHA in the PR corresponds to the SHA of the image within the k8s staging repo. (This is under the **Name** column) @@ -50,7 +61,7 @@ Creating a new release of network proxy involves releasing a new version of the -3. Finally, update kubernetes/kubernetes with the new client library and images. +4. Finally, update kubernetes/kubernetes with the new client library and images. An example PR can be found here: [https://github.com/kubernetes/kubernetes/pull/94983](https://github.com/kubernetes/kubernetes/pull/94983)