Document the Broker's versioning strategy (openshift#810)

* Document the Broker's versioning strategy

- Document broker's compatibility with APBs
- Document versioning and branching strategy

* Address review comments

README.md

@@ -151,6 +151,51 @@ Let's walk through an `oc cluster up` based setup.
 1. View the route for MediaWiki and verify the wiki is up and running.
     * Observe that mediawiki123 is on deployment '#2', having been automatically redeployed
 
+# Versioning
+
+Our release versions align with
+[openshift/origin](https://github.com/openshift/origin/). For more detailed
+information see our [version document](docs/versioning.md).
+
+# Compatibility
+
+## APB Compatibility Matrix
+
+| ansible-service-broker                      | APB runtime 1 | APB runtime 2 |
+|---------------------------------------------|---------------|---------------|
+| ansible-service-broker release-1.0, v3.7    |       ✓       |       X       |
+| ansible-service-broker release-1.1, v3.9    |       ✓       |       ✓       |
+| ansible-service-broker HEAD                 |       ✓       |       ✓       |
+
+Key:
+
+* `✓` Supported.
+* `X` Will not work. Not supported.
+
+Ansible Playbook Bundle images are built on the [apb-base
+image](https://github.com/ansibleplaybookbundle/apb-base). Starting with
+apb-base 1.1, a new APB runtime was introduced and captured in the label
+[`com.redhat.apb.runtime`](https://github.com/ansibleplaybookbundle/apb-base/blob/master/Dockerfile-latest#L3).
+Currently, there are two APB runtime versions:
+
+* APB runtime 1 - all APBs tagged `release-1.0` as well as APBs with no
+  `"com.redhat.apb.runtime"` label.
+* APB runtime 2 - all APBs tagged `release-1.1` as well as APBs with label
+  `"com.redhat.apb.runtime"="2"`.
+
+You can examime the runtime of a
+particular APB with `docker inspect $APB --format "{{ index
+.Config.Labels \"com.redhat.apb.runtime\" }}"`. An APB without a
+`"com.redhat.apb.runtime"` label is APB runtime 1. For example:
+
+```
+$ docker inspect docker.io/ansibleplaybookbundle/mediawiki-apb:latest --format "{{ index .Config.Labels \"com.redhat.apb.runtime\" }}"
+2
+
+# No label on release-1.0
+$ docker inspect docker.io/ansibleplaybookbundle/mediawiki-apb:release-1.0 --format "{{ index .Config.Labels \"com.redhat.apb.runtime\" }}"
+```
+
 # Contributing
 
 First, **start with the** [Contributing Guide](CONTRIBUTING.md).

docs/versioning.md

@@ -0,0 +1,32 @@
+Versioning Strategy
+===================
+
+# Version Format
+
+The Broker version is stored in the broker's RPM spec file,
+[ansible-service-broker.spec](../ansible-service-broker.spec), and is in the
+form of MAJOR.MINOR.PATCH incremented by the following rules:
+
+* MAJOR version when incompatible API changes are made.
+* MINOR version when a new version of
+  [openshift/origin](https://github.com/openshift/origin) is being targeted.
+* PATCH version when tagged via `tito tag`.
+
+NOTE: The first official release of the broker,
+[`1.0.x`](https://github.com/openshift/ansible-service-broker/tree/ansible-service-broker-1.0.1-1),
+targeted OpenShift Origin [release
+v3.7.0](https://github.com/openshift/origin/releases/tag/v3.7.0). Following the
+versioning rules, the version was bumped to `1.1.x` for OpenShift Origin [release
+v3.9.0](https://github.com/openshift/origin/tree/release-3.9) and again to
+`1.2.x` for OpenShift Origin release v3.10.0.
+
+# Branching and Tagging
+
+All development work is done on the [`master`
+branch](https://github.com/openshift/ansible-service-broker/tree/master). New
+branches are created when a submitted Pull Request is targeting a future release.
+This is done to allow Pull Requests to move forward when new features are no
+longer being added to the currently targeted OpenShift releases. When a new
+branch is created, it will be named `release-MAJOR.MINOR` and the version in
+the `master` branch will be bumped based on the rules in [Version
+Format](#VersionFormat).