New dotnet sdk versioning proposals

[tg123]

The problem

• Kubernets version compatibility

  A client should be skewed no more than one minor version from the master, but may lead the master by up to one minor version. For example, a v1.3 master should work with v1.1, v1.2, and v1.3 nodes, and should work with v1.2, v1.3, and v1.4 clients.

  See detail:
  https://github.com/kubernetes/community/blob/master/contributors/design-proposals/release/versioning.md#supported-releases-and-component-skew

• dotnet SDK compatibility

  In real world, users somehow prefer not to update to latest version for many reasons.
  Kubernetes dotnet client is trying to support most popular kubernetes version without introducing breaking changes, as a result PR Gen v1.18.0 #385 and PR Gen v1.17.0 #334 were postponed to get merged.

  However, cutting edge users still want client SDK to support latest kuberentes APIs.

New version format should:

• should be easy to understand for which kubernetes versions are supported or generated based on
• should follow nuget versioning basics https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-basics

Proposals and solutions

draft some proposals for open discussion

Align with other client SDKs, Python, Java.

• Update Major version for every single Minor kubernetes version.
• Per Semantic Versioning, Major SDK update may introduce breaking changes

Java SDK solution https://github.com/kubernetes-client/java/blob/master/README.md#compatibility

|  client version  | 1.11      | 1.12     | 1.13     |  1.14     |  1.15    |
|------------------|-----------|----------|----------|-----------|----------|
|  3.0.0           |  ✓        |  -       |  -       | -         | -        |
|  4.0.0           |  +        |  ✓       |  -       | -         | -        |
|  5.0.0           |  +        |  +       |  ✓       | -         | -        |
|  6.0.1           |  +        |  +       |  +       | ✓         | -        |
|  7.0.0           |  +        |  +       |  +       | +         | ✓        |

Key: 

* `✓` Exactly the same features / API objects in both java-client and the Kubernetes
version.
* `+` java-client has features or api objects that may not be present in the
Kubernetes cluster, but everything they have in common will work.
* `-` The Kubernetes cluster has features the java-client library can't use
(additional API objects, etc).

Pack kubernetes version into SDK version

• Like the solution above, the dotnet SDK version would be <Kubernetes Major>.<Kubernetes Minor>.<SDK updates>

such convention would help users understand better, but which doe

• A workaround for issue above is to pack Major and Minor into one number, like <Kubernetes Major Kubernetes Minor (6 digits padding)>.<SDK update>.<SDK patch>

Docker image tag like Suffix

In additional to solutions above, also provide multiple branches build with suffix. (version with suffix will be treated as prerelease in nuget)

• <Major>.<Minor>.<Patch> <- this one should be equal to last but without any suffix
• <Major>.<Minor>.<Patch>-K1.14
• <Major>.<Minor>.<Patch>-K1.15
• <Major>.<Minor>.<Patch>-K1.16

Upgrade to new version format

Current version is 1.6.x, new version format should be Semantic Newer

[tg123]

I, personally, prefer solution 2 + solution 3.
This is an open discussion, any comments are welcomed.

[brendandburns]

Hrm, I think it's tricky, the trouble with encoding the Kubernetes version is that you either lose data (e.g. no opportunity for C# patch releases) or you end up with N different libraries (1.1.1-k1.14, 1.1.1-k1.15, etc)

That's why we went with the scheme that we use for the Java library.

I'm not 100% wedded to it, but it's what I would vote for (but I'm biased)