update information about versions and releases

This change updates the language in the readme and release documents to
highlight new decisions made by the project maintainers about the
version numbers for the project. For more information about this
decision, please see the project meeting recordings for
[2023-08-09][mtg1] and [2023-08-23][mtg2].

[mtg1]: https://www.youtube.com/watch?v=XGjGGsq1Uns
[mtg2]: https://www.youtube.com/watch?v=8yAj1XmeL0k

Author: elmiko

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)