Clarifying approach to versioning

RELEASE.md

@@ -9,20 +9,10 @@ The Service APIs project is an API project that has the following two components
 This repository is the home for both of the above components.
 
 ## Versioning strategy
+The versioning strategy for this project is covered in detail in [the release
+documentation].
 
-Releases in this repository follow Go module versioning conventions and
-semantic versioning.
-During the `alpha` and `beta` stage of the API, version tags will take the form
-of `v0.x.y`.
-Minor version must be incremented whenever a new API version is introduced for
-any resource or even when smaller backwards-compatible additions are made to the API.
-Bug fixes and clarifications in the spec will lead to patch number being incremented.
-
-During GA (when `apiVersion` changes to `v1`), the Git version tag will be bumped
-up to `v1.0.0`.
-
-> The first release candidate was tagged as `v1alpha1-rc1`. It predates this
-document and is an exception.
+[the release documentation]: https://kubernetes-sigs.github.io/service-apis/releases/#versioning
 
 ## Releasing a new version
 

docs-src/releases.md

@@ -18,10 +18,38 @@ Service API releases will include four components:
 
 ## Versioning
 
-Versioning will be completely separate from the Kubernetes release process, but
-similar methodology will be used. Service API versions will use the [same
-version level requirements as other Kubernetes
-features](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
+This project uses 2 different but related forms of versioning:
+
+- [Kubernetes API Versioning] (example: v1alpha1)
+- [Semantic Versioning] (example: v0.1.0)
+
+Each new API version will be released with a new semantic version. For example,
+v1alpha1 was released with v0.1.0. Before we release an API version, we may
+provide some release candidates such as v0.1.0-rc1 as a way to evaluate a new
+API version before it is formally released. All releases will be compatible with
+[Go modules versioning].
+
+As the API evolves, we will make intermediate releases that improve upon an
+existing API version. These releases will be fully backwards compatible and will
+be limited to either bug fixes or additions to the API.
+
+This project may release one or more additional alpha API versions. New alpha
+API versions may include breaking changes such as removing or renaming fields or
+resources.
+
+Following [Semantic Versioning], new patch releases will be limited to bug
+fixes. New minor releases may include new fields or resources in addition to bug
+fixes. New API versions will be released with new minor or major versions.
+
+Our changelog and release notes will always include both the semantic version
+and API version(s) included in the release. 
+
+[Kubernetes API Version]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions
+[Semantic Versioning]: https://semver.org/
+[Go modules versioning]: https://golang.org/ref/mod#versions
+
+> The first release candidate was tagged as `v1alpha1-rc1`. It predates this
+documentation and is an exception.
 
 ## Installation
 

docs/releases/index.html

@@ -645,10 +645,31 @@ <h1 id="releases">Releases</h1>
 <li>Conversion webhooks to convert resources between API versions.</li>
 </ul>
 <h2 id="versioning">Versioning</h2>
-<p>Versioning will be completely separate from the Kubernetes release process, but
-similar methodology will be used. Service API versions will use the <a href="https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions">same
-version level requirements as other Kubernetes
-features</a>.</p>
+<p>This project uses 2 different but related forms of versioning:</p>
+<ul>
+<li>[Kubernetes API Versioning] (example: v1alpha1)</li>
+<li><a href="https://semver.org/">Semantic Versioning</a> (example: v0.1.0)</li>
+</ul>
+<p>Each new API version will be released with a new semantic version. For example,
+v1alpha1 was released with v0.1.0. Before we release an API version, we may
+provide some release candidates such as v0.1.0-rc1 as a way to evaluate a new
+API version before it is formally released. All releases will be compatible with
+<a href="https://golang.org/ref/mod#versions">Go modules versioning</a>.</p>
+<p>As the API evolves, we will make intermediate releases that improve upon an
+existing API version. These releases will be fully backwards compatible and will
+be limited to either bug fixes or additions to the API.</p>
+<p>This project may release one or more additional alpha API versions. New alpha
+API versions may include breaking changes such as removing or renaming fields or
+resources.</p>
+<p>Following <a href="https://semver.org/">Semantic Versioning</a>, new patch releases will be limited to bug
+fixes. New minor releases may include new fields or resources in addition to bug
+fixes. New API versions will be released with new minor or major versions.</p>
+<p>Our changelog and release notes will always include both the semantic version
+and API version(s) included in the release. </p>
+<blockquote>
+<p>The first release candidate was tagged as <code>v1alpha1-rc1</code>. It predates this
+documentation and is an exception.</p>
+</blockquote>
 <h2 id="installation">Installation</h2>
 <p>This project will be responsible for providing straightforward and reliable ways
 to install releases of Service APIs.</p>