docs: clarify versioning and kubernetes compatibility

README.md

@@ -176,40 +176,50 @@ There are several more JS and TS examples in the [examples](https://github.com/k
 
 # Compatibility
 
-Prior to the `0.13.0` release, release versions did not track Kubernetes versions. Starting with the `0.13.0`
-release, we will increment the minor version whenever we update the minor Kubernetes API version
-(e.g. `1.19.x`) that this library is generated from.
-
-`request` was migrated to `node-fetch` as the HTTP(S) backend for release `1.0.0` tracked in #754
-
-`node-fetch` was migrated to `undici` which is the native node.js fetch package for release `2.0.0` tracked in #2306
-
-Generally speaking newer clients will work with older Kubernetes, but compatibility isn't 100% guaranteed.
-
-| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33 | 1.34 |
-| -------------- | -------------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
-| 0.19.x         | -              | ✓    | x    | x    | x    | x    | x    | x    |
-| 0.20.x         | -              | +    | ✓    | x    | x    | x    | x    | x    |
-| 0.21.x         | -              | +    | +    | ✓    | x    | x    | x    | x    |
-| 0.22.x         | -              | +    | +    | +    | ✓    | x    | x    | x    |
-| 1.0.x          | -              | +    | +    | +    | +    | ✓    | x    | x    |
-| 1.1.x          | -              | +    | +    | +    | +    | ✓    | x    | x    |
-| 1.2.x          | -              | +    | +    | +    | +    | +    | ✓    | x    |
-| 1.3.x          | -              | +    | +    | +    | +    | +    | ✓    | x    |
-| 1.4.x          | -              | +    | +    | +    | +    | +    | +    | ✓    |
-
-Key:
-
-- `✓` Exactly the same features / API objects in both javascript-client and the Kubernetes
-  version.
-- `+` javascript-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 javascript-client library can't use
-  (additional API objects, etc).
-- `x` The Kubernetes cluster has no guarantees to support the API client of
-  this version, as it only promises _n_-2 version support. It is not tested,
-  and operations using API versions that have been deprecated and removed in
-  later server versions won't function correctly.
+## Package versioning
+
+Client releases follow [Semantic Versioning](https://semver.org/):
+
+- **Major:** new Kubernetes API targets and incompatible client changes. Regeneration may remove
+  exported clients or models and change existing TypeScript types.
+- **Minor:** backward-compatible features.
+- **Patch:** backward-compatible bug and security fixes.
+
+We align major client releases with new Kubernetes API targets, as discussed in
+[#2582](https://github.com/kubernetes-client/javascript/issues/2582#issuecomment-3145057737).
+Client and Kubernetes version numbers do not match. Check the release notes when upgrading majors.
+
+The [1.0.0 release](https://github.com/kubernetes-client/javascript/releases/tag/1.0.0) migrated from
+`request` to `node-fetch` and became ESM-only. The
+[2.0.0 release](https://github.com/kubernetes-client/javascript/releases/tag/2.0.0) migrated from
+`node-fetch` to the npm `undici` package and changed supported Node.js versions.
+
+## Generated Kubernetes API targets
+
+This table lists the Kubernetes API specification used to generate each client version.
+
+| Client version | Generated Kubernetes API target |
+| -------------- | ------------------------------- |
+| 0.19.0         | 1.27                            |
+| 0.20.0         | 1.28                            |
+| 0.21.0         | 1.29                            |
+| 0.22.0         | 1.30                            |
+| 1.0.0          | 1.32                            |
+| 1.1.2          | 1.32                            |
+| 1.2.0          | 1.33                            |
+| 1.3.0          | 1.33                            |
+| 1.4.0          | 1.34                            |
+| 2.0.0–2.0.2    | 1.36                            |
+| 3.0.0          | 1.37                            |
+
+## Compatibility with clusters
+
+Clients generally work with older or newer clusters when both support the APIs your application
+uses. New APIs may be unavailable on older clusters, and deprecated APIs may be removed from newer
+clusters or clients. The generation targets above do not guarantee compatibility with every cluster.
+
+See the [Kubernetes API deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/)
+and client release notes, and test against the cluster versions your application supports.
 
 # Known Issues