Version the CSI protobuf

This patch versions the generated CSI protobuf and provides a Travis-CI
build step that verifies the protobuf is up-to-date before allowing any
changes to be merged.

Additionally this patch also adds minimal Go language bindings in order
to verify the specification. Finally, scaffolding was put into place in
order to support Cxx language bindings in the future as well.

Author: akutz

.gitignore

@@ -1,2 +1,2 @@
-csi.proto
-csi.pb.go
+/csi.proto.tmp
+.DS_Store

.travis.yml

@@ -1,26 +1,38 @@
-go_import_path: github.com/container-storage-interface/spec
+# Setting "sudo" to false forces Travis-CI to use its
+# container-based build infrastructure, which has shorter
+# queue times.
+sudo: false
 
-language: go
+# Use the newer Travis-CI build templates based on the
+# Debian Linux distribution "Trusty" release.
+dist: trusty
 
-go:
-  - 1.8.x
+# Selecting C as the language keeps the container to a
+# minimum footprint.
+language: c
 
-before_install:
-  - gem install gist
-  - curl -LO https://github.com/google/protobuf/releases/download/v3.3.0/protoc-3.3.0-linux-x86_64.zip
-  - unzip protoc-3.3.0-linux-x86_64.zip
-  - chmod +x bin/protoc
-  - export PATH="$(pwd)/bin:$PATH"
+jobs:
+  include:
 
-install:
-  - go get -u github.com/golang/protobuf/proto
-  - go get -u github.com/golang/protobuf/protoc-gen-go
-  - go get -u google.golang.org/grpc
-  - CSI_SPEC_FILE=spec.md make csi.proto
+    # The test stage validates that the protobuf file was updated
+    # correctly prior to being committed.
+    - stage:               test
+      script:              make
 
-script:
-  - make csi.pb.go
+    # The lang stages validate the specification using
+    # language-specific bindings.
 
-after_success:
-  - printf "%s" "$GITHUB_API_TOKEN" > "${HOME}/.gist"
-  - gist -d "https://travis-ci.org/container-storage-interface/spec/jobs/${TRAVIS_BUILD_ID}" *.{proto,go}
+    # Lang stage: Cxx
+    - stage:               lang
+      script:              make -C lib/cxx
+
+    # Lang stage: Go
+    - stage:               lang
+      language:            go
+      go:                  1.8.3
+      go_import_path:      github.com/container-storage-interface/spec
+      install:
+        - make -C lib/go protoc
+        - make -C lib/go protoc-gen-go
+      script:
+        - make -C lib/go

CONTRIBUTING.md

@@ -17,9 +17,11 @@ This also applies to the code snippets in the markdown files.
 
 ## Git commit
 
+Prior to committing code please run `make` in order to update the protobuf file and any language bindings.
+
 ### Commit Style
 
-Each commit should represent a single logical (atomic) change: this makes your changes easier to review. 
+Each commit should represent a single logical (atomic) change: this makes your changes easier to review.
 
 * Try to avoid unrelated cleanups (e.g., typo fixes or style nits) in the same commit that makes functional changes.
   While typo fixes are great, including them in the same commit as functional changes makes the commit history harder to read.

Makefile

@@ -1,8 +1,47 @@
 all: build
 
-include csi.mk
+CSI_SPEC := spec.md
+CSI_PROTO := csi.proto
 
-build: $(CSI_PROTO) $(CSI_GOSRC)
+# This is the target for building the temporary CSI protobuf file.
+#
+# The temporary file is not versioned, and thus will always be
+# built on Travis-CI.
+$(CSI_PROTO).tmp: $(CSI_SPEC)
+	cat $? | \
+	  sed -n -e '/```protobuf$$/,/```$$/ p' | \
+	  sed -e 's@^```.*$$@////////@g' > $@
+
+# This is the target for building the CSI protobuf file.
+#
+# This target depends on its temp file, which is not versioned.
+# Therefore when built on Travis-CI the temp file will always
+# be built and trigger this target. On Travis-CI the temp file
+# is compared with the real file, and if they differ the build
+# will fail.
+#
+# Locally the temp file is simply copied over the real file.
+$(CSI_PROTO): $(CSI_PROTO).tmp
+ifeq (true,$(TRAVIS))
+	diff "$@" "$?"
+else
+	diff "$@" "$?" > /dev/null 2>&1 || cp -f "$?" "$@"
+.PHONY: $(CSI_PROTO).tmp
+endif
+
+build: $(CSI_PROTO)
+
+# If this is not running on Travis-CI then for sake of convenience
+# go ahead and update the language bindings as well.
+ifneq (true,$(TRAVIS))
+build:
+	$(MAKE) -C lib/go
+	$(MAKE) -C lib/cxx
+endif
 
 clean:
-	rm -f $(CSI_PROTO) $(CSI_GOSRC)
+
+clobber: clean
+	rm -f $(CSI_PROTO) $(CSI_PROTO).tmp
+
+.PHONY: clean clobber

README.md

@@ -2,49 +2,4 @@
 
 ![CSI Logo](logo.png)
 
-This project contains the CSI [specification](spec.md). Please see the
-[build reference](#build-reference) section for information on how to
-generate the protobuf or Go source files.
-
-## Build Reference
-This section describes how to generate the CSI protobuf file, generate
-Go sources from the protobuf, and which environment variables can
-influence the build process.
-
-### Generate Protobuf
-The CSI protobuf can be generated with the following command:
-
-```bash
-$ make csi.proto
-```
-
-In the above example the protobuf file is generated by parsing a `spec.md`
-from a remote git repository (this one in fact). However, it's also
-possible to generate the protobuf from a local spec file:
-
-```bash
-$ CSI_SPEC_FILE=spec.md make csi.proto
-```
-
-### Generate Go Source
-The following command generates the Go source file from the protobuf:
-
-```bash
-$ make csi.pb.go
-```
-
-### Build Options
-It's also possible to influence the location from which the CSI specification
-is retrieved with the following environment variables:
-
-| Name | Description | Default |
-|------|-------------|---------|
-| `CSI_SPEC_FILE` | The path to a local spec file used to generate the protobuf | |
-| `CSI_GIT_OWNER` | The GitHub user or organization that owns the git repository that contains the CSI spec file | `container-storage-interface` |
-| `CSI_GIT_REPO` | The GitHub repository that contains the CSI spec file | `spec` |
-| `CSI_GIT_REF` | The git ref to use when getting the CSI spec file. This value can be a branch name, a tag, or a git commit ID | `master` |
-| `CSI_SPEC_NAME` | The name of the CSI spec markdown file | `spec.md` |
-| `CSI_SPEC_PATH` | The remote path of the CSI markdown file | |
-| `CSI_PROTO_NAME` | The name of the protobuf file to generate. This value should not include the file extension | `csi` |
-| `CSI_PROTO_DIR` | The path of the directory in which the protobuf and Go source files will be generated. If this directory does not exist it will be created. | `.` |
-| `CSI_PROTO_ADD` | A list of additional protobuf files used when building the Go source file | |
+This project contains the CSI [specification](spec.md) and [protobuf](csi.proto) files.