Merge pull request moby#2349 from tossmilestone/stabilize-api

Stabilize the api proto descriptors in swarmkit

Protobuild.toml

@@ -30,3 +30,7 @@ plugins = ["grpc", "deepcopy", "storeobject", "raftproxy", "authenticatedwrapper
   "google/protobuf/field_mask.proto" = "github.com/gogo/protobuf/types"
   "google/protobuf/timestamp.proto" = "github.com/gogo/protobuf/types"
   "google/protobuf/duration.proto" = "github.com/gogo/protobuf/types"
+
+[[descriptors]]
+prefix = "github.com/docker/swarmkit/api"
+target = "api/api.pb.txt"

api/README.md

@@ -6,3 +6,19 @@ $ make generate
 ```
 
 Click [here](https://github.com/google/protobuf) for more information about protobuf.
+
+The `api.pb.txt` file contains merged descriptors of all defined services and messages.
+Definitions present here are considered frozen after the release.
+
+At release time, the current `api.pb.txt` file will be moved into place to
+freeze the API changes for the minor version. For example, when 1.0.0 is
+released, `api.pb.txt` should be moved to `1.0.txt`. Notice that we leave off
+the patch number, since the API will be completely locked down for a given
+patch series.
+
+We may find that by default, protobuf descriptors are too noisy to lock down
+API changes. In that case, we may filter out certain fields in the descriptors,
+possibly regenerating for old versions.
+
+This process is similar to the [process used to ensure backwards compatibility
+in Go](https://github.com/golang/go/tree/master/api).