[WIP] 📖 Versioning and Branching Strategy

Author: DirectXMan12

README.md

@@ -13,6 +13,21 @@ Documentation:
 - [Creating a controller](https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#example-New)
 - [Example `main.go`](https://github.com/kubernetes-sigs/controller-runtime/blob/master/example/main.go)
 
+# Versioning, Maintenance, and Compatibility
+
+The full documentation can be found at [VERSIONING.md](VERSIONING.md), but TL;DR:
+
+Users:
+
+- We follow [Semantic Versioning (semver)](https://semver.org)
+- Use releases with your dependency management to ensure that you get compatible code
+- The master branch contains all the latest code, some of which may break compatibility (so "normal" `go get` is not reccomended)
+
+Contributors:
+
+- All code PR must be labeled with :bug: (patch fixes), :sparkles: (backwards-compatible features), or :warning: (breaking changes)
+- Breaking changes will find their way into the next major release, other changes will go into an semi-immediate patch or minor release
+
 ## Community, discussion, contribution, and support
 
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).

VERSIONING.md

@@ -0,0 +1,206 @@
+# Versioning and Branching in controller-runtime
+
+*NB*: this also applies to controller-tools.
+
+## TL;DR:
+
+### Users
+
+- We follow [Semantic Versioning (semver)](https://semver.org)
+- Use releases with your dependency management to ensure that you get
+  compatible code
+- The master branch contains all the latest code, some of which may break
+  compatibility (so "normal" `go get` is not reccomended)
+
+### Contributors
+
+- All code PR must be labeled with :bug: (patch fixes), :sparkles:
+  (backwards-compatible features), or :warning: (breaking changes)
+
+- Breaking changes will find their way into the next major release, other
+  changes will go into an semi-immediate patch or minor release
+
+- Please *try* to avoid breaking changes when you can.  They make users
+  face difficult decisions (when do I go through the pain of upgrading),
+  and make life hard for maintainers and contributors (dealing with
+  differences on stable branches).
+
+### Mantainers
+
+Don't be lazy, read the rest of this doc :-)
+
+## Overview
+
+controller-runtime (and friends) follow [Semantic
+Versioning](https://semver.org).  I'd reccomend reading the aforementioned
+link if you're not familiar, but essentially, for any given release X.Y.Z:
+
+- an X (*major*) release indicates a set of backwards-compatible code.
+  Changing X means there's a breaking change.
+
+- a Y (*minor*) release indicates a minimum feature set.  Changing Y means
+  the addition of a backwards-compatible feature.
+
+- a Z (*patch*) release indicates minimum set of bugfixes.  Changing
+  Z means a backwards-compatible change that doesn't add functionality.
+
+*NB*: If the major release is `0`, any minor release may contain breaking
+changes.
+
+These guarantees extend to all code exposed in public APIs of
+controller-runtime. This includes code both in controller-runtime itself,
+*plus types from dependencies in public APIs*.  Types and functions not in
+public APIs are not considered part of the guarantee.
+
+In order to easily maintain the guarantees, we have a couple of processes
+that we follow.
+
+## Branches
+
+controller-runtime contains two types of branches: the *master* branch and
+*release-X* branches.
+
+The *master* branch is where development happens.  All the latest and
+greatest code, including breaking changes, happens on master.
+
+The *release-X* branches contain stable, backwards compatible code.  Every
+major (X) release, a new such branch is created.  It is from these
+branches that minor and patch releases are tagged.
+
+The maintainers are responsible for updating the contents of this branch;
+generally, this is done just before a release using release tooling that
+filters and checks for changes tagged as breaking (see below).
+
+### Tooling
+
+***TODO***
+
+## PR Process
+
+Every PR should be annotated with an icon indicating whether it's
+a:
+
+- Breaking change: :warning: (`:warning:`)
+- Non-breaking feature: :sparkles: (`:sparkles:`)
+- Patch fix: :bug: (`:bug:`)
+- Docs: :book: (`:book:`)
+- Infra/Tests/Other: :running: (`:running:`)
+
+Individual commits may be tagged separately, but will generally be assumed
+to match the PR. For instance, if you have a bugfix in with a breaking
+change, it's generally encouraged to submit the bugfix separately, but if
+you must put them in one PR, mark the commit separately.
+
+## Release Process
+
+Minor and patch releases are generally done immediately after a feature or
+bugfix is landed, or sometimes a series of features tied together.
+
+Major releases are done once a sufficient amount of breaking changes are
+accrued.  Since we don't intend to have a ton of these, the maintainers
+will evaluate when to do a major release as it comes up.
+
+### Exact Steps
+
+***TODO***
+
+### Breaking Changes
+
+Try to avoid breaking changes.  They make life difficult for users, who
+have to rewrite their code when they eventually upgrade, and for
+maintainers/contributors, who have to deal with differences between master
+and stable branches.
+
+That being said, we'll occaisonally want to make breaking changes. They'll
+be merged onto master, but won't make it into a release immediately (see
+[Release Proccess](#release-process)).
+
+If you're going to make a breaking change, please make sure to explain in
+detail why it's helpful.  Is it necessary to cleanly resolve an issue?
+Does it improve API ergonomics?
+
+Maintainers should treat breaking changes with caution, and evaluate
+potential non-breaking solutions (see below).
+
+*NB*: Pre-1.0 releases treat breaking changes a bit more lightly.  We'll
+still consider carefully, but the pre-1.0 timeframe is useful for
+converging on a ergonomic API.
+
+#### Avoiding breaking changes
+
+***TODO***
+
+##### Solutions to avoid
+
+- **Confusingly duplicate methods, functions, or variables.**
+
+  For instance, suppose we have an interface method `List(ctx
+  context.Context, options *ListOptions, obj runtime.Object) error`, and
+  we decide to switch it so that options come at the end, parametrically.
+  Adding a new interface method `ListParametric(ctx context.Context, obj
+  runtime.Object, options... ListOption)` is probably not the right
+  solution:
+
+   - Users will intuitively see `List`, and use that in new projects, even
+     if it's marked as deprecated.
+   
+   - Users who don't notice the deprecation may be confused as to the
+     difference between `List` and `ListParametric`.
+   
+   - It's not immediately obvious in isolation (e.g. in surrounding code)
+     why the method is called `ListParametric`, and may cause confusion
+     when reading code that makes use of that method.
+
+  In this case, it may be better to make the breaking change, and then
+  eventually do a major release.
+
+  ***TODO***: make a better suggestion
+  
+## Why don't we...
+
+### Use "next"-style branches
+
+Development branches:
+
+- don't win us much in terms of maintenance in the case of breaking
+  changes (we still have to merge/manage multiple branches for development
+  and stable) 
+  
+- can be confusing to contributors, who often expect master to have the
+  latest changes.
+
+### Never break compatibility
+
+Never doing a new major release could be an admirable goal, but gradually
+leads to API cruft.
+
+Since one of the goals of controller-runtime is to be a friendly and
+intuitive API, we want to avoid too much API cruft over time, and
+occaisonal breaking changes in major releases help accomplish that goal.
+
+Furthermore, our dependency on Kubernetes libraries makes this difficult
+(see below)
+
+### Always assume we've broken compatibility
+
+*a.k.a. k8s.io/client-go style*
+
+While this makes life easier (a bit) for maintainers, it's problematic for
+users.  While breaking changes arrive sooner, upgrading becomes very
+painful.
+
+Furthermore, we still have to maintain stable branches for bugfixes, so
+the maintenance burden isn't lessened by a ton.
+
+### Extend compatibility guarantees to all dependencies
+
+This is very difficult with the number of Kubernetes dependencies we have.
+Kubernetes dependencies tend to either break compatibility every major
+release (e.g. k8s.io/client-go, which loosely follows semver), or at
+a whim (many other Kubernetes libraries).
+
+If we limit to the few objects we expose, we can better inform users about
+how *controller-runtime itself* has changed in a given release.  Then,
+users can make informed decisions about how to proceed with any direct
+uses of Kubernetes dependencies their controller-runtime-based application
+may have.