diff --git a/README.md b/README.md index 003b572b3a..18e4d1d6ce 100644 --- a/README.md +++ b/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). diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000000..d689fd4e16 --- /dev/null +++ b/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).