Merge pull request #27 from openconfig/wenbli-dev

Add to README definition of backwards compatibility and notes on versioning.

README.md

@@ -2,19 +2,35 @@
 
 Continuous integration for OpenConfig models.
 
-## Versioning and Making Changes
+## Usage Notes and Versioning
 
-`models-ci` should always be used with a specified major version within the
-repository's `cloudbuild.yaml`, e.g.
+In order to avoid backwards-incompatible new changes from affecting and breaking
+CI, a user repository's `cloudbuild.yaml` should always use `models-ci` with a
+specified **major** version only, e.g.
 
-`go get github.com/openconfig/models-ci@v0`
+`go get github.com/openconfig/models-ci@v1`
 
 New minor and patch versions are guaranteed to be backwards compatible per
 [semantic versioning rules](https://semver.org/)
 
-Each `cloudbuild.yaml`-incompatible change to `models-ci` should come with major
-version updates. Activated repositories should then make a change to
-`cloudbuild.yaml` to make use of the updated version.
+A backwards compatible change is defined to mean a change not requiring changes
+to any possible `cloudbuild.yaml` usage provided by the existing `models-ci`.
+
+-   Example of major revision changes:
+    -   Existing `cmd_gen` flag altered in behaviour or deleted by new
+        `models-ci` change.
+    -   Changes to how an existing validator is set-up or ran within
+        `cloudbuild.yaml`.
+-   Minor and patch revisions encompass the remaining changes, e.g.
+    -   Adding a new `cmd_gen` flag.
+    -   Adding a new validator.
+    -   Changing an existing validator's behaviour, or any other part of
+        `models-ci`, that doesn't break the current `cloudbuild.yaml` interface.
+
+When changing `models-ci`, it's ok to be liberal when deciding whether to bump
+up major revisions. It simply requires an update in `cloubuild.yaml` in user
+repos to make use of the new features. The main point is to avoid breaking
+existing `cloudbuild.yaml`.
 
 ## Purpose
 
@@ -135,6 +151,7 @@ GitHub PR.
 
 Validator         | Installation
 ----------------- | -------------------------------------------------------
+confd             | Binary unzipped during build
 regexp            | Files moved into GOPATH from its folder during CI build
 pyang & pyangbind | pip
 oc-pyang          | git clone