api: generate merged descriptors when building protobufs

When we generate protobufs, descriptors outlining all messages and
services are merged into a single file that can be used to identify
unexpected changes to the API that may affect stability. We follow a
similar process to Go's stability guarantees using the protobuf
descriptors to identify changes before they become a problem.

Please see README.md for details.

Signed-off-by: Stephen J Day <[email protected]>

Protobuild.toml

@@ -27,3 +27,29 @@ plugins = ["grpc", "fieldpath"]
   "google/protobuf/descriptor.proto" = "github.com/gogo/protobuf/protoc-gen-gogo/descriptor"
   "google/protobuf/field_mask.proto" = "github.com/gogo/protobuf/types"
   "google/protobuf/timestamp.proto" = "github.com/gogo/protobuf/types"
+
+# Aggregrate the API descriptors to lock down API changes.
+[[descriptors]]
+prefix = "github.com/containerd/containerd/api"
+target = "api/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]
+
+# Lock down runc config
+[[descriptors]]
+prefix = "github.com/containerd/containerd/linux/runcopts"
+target = "linux/runcopts/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]
+
+[[descriptors]]
+prefix = "github.com/containerd/containerd/windows/hcsshimopts"
+target = "windows/hcsshimopts/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]

api/README.md

@@ -0,0 +1,18 @@
+This directory contains the GRPC API definitions for contaienrd.
+
+All defined services and messages have been aggregated into `*.pb.txt`
+descriptors files in this directory. Definitions present here are considered
+frozen after the release.
+
+At release time, the current `next.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, `next.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).