Merge pull request #518 from elmiko/update-version-info

update information about versions and releases

Author: k8s-ci-robot

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

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 [email protected]: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
 
     <img src="https://user-images.githubusercontent.com/7691399/106816880-09040600-6644-11eb-8907-f50c53dfe475.png" width="400px" height="300px" /> <img src="https://user-images.githubusercontent.com/7691399/106815303-a4e04280-6641-11eb-82d2-4ef4fb34437a.png" width="400px" height="300px" />
 
-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)