initial documentation and rules

README.md

@@ -1,2 +1,50 @@
-# csi-build-rules
-common build and test rules for CSI apps
+# [csi-build-rules](https://github.com/kubernetes-csi/csi-build-rules)
+
+These build and test rules can be shared between different Go projects
+without modifications. Customization for the different projects happen
+in the top-level Makefile.
+
+The rules include support for building and pushing Docker images, with
+the following features:
+ - one or more command and image per project
+ - push canary and/or tagged release images
+ - automatically derive the image tag(s) from repo tags
+ - the source code revision is stored in a "revision" image label
+ - never overwrites an existing release image
+
+Usage
+-----
+
+The expected repository layout is:
+ - `cmd/*/*.go` - source code for each command
+ - `cmd/*/Dockerfile` - docker file for each command or
+   Dockerfile in the root when only building a single command
+ - `Makefile` - includes `build-rules/build.make` and sets
+   configuration variables
+ - `.travis.yml` - a symlink to `build-rules/.travis.yml`
+
+To create a release, tag a certain revision with a name that
+starts with `v`, for example `v1.0.0`, then `make push`
+while that commit is checked out.
+
+It does not matter on which branch that revision exists, i.e. it is
+possible to create releases directly from master. A release branch can
+still be created for maintenance releases later if needed.
+
+Release branches are expected to be named `release-x.y` for releases
+`x.y.z`. Building from such a branch creates `x.y-canary`
+images. Building from master creates the main `canary` image.
+
+Sharing and updating
+--------------------
+
+[`git subtree`](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.txt)
+is the recommended way of maintaining a copy of the rules inside the
+`build-rules` directory of a project. This way, it is possible to make
+changes also locally, test them and then push them back to the shared
+repository at a later time.
+
+Cheat sheet:
+
+- `git subtree pull --prefix=build-rules https://github.com/kubernetes-csi/csi-build-rules.git master` - update local copy to latest upstream
+- edit, `git commit`, `git subtree push --prefix=build-rules [email protected]:<user>/csi-build-rules.git <my-new-or-existing-branch>` - push to a new branch before submitting a PR

build.make

@@ -0,0 +1,99 @@
+# Copyright 2017 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+.PHONY: build-% build container-% container push-% push clean test
+
+# A space-separated list of all commands in the repository, must be
+# set in main Makefile of a repository.
+# CMDS=
+
+# This is the default. It can be overridden in the main Makefile after
+# including build.make.
+REGISTRY_NAME=quay.io/k8scsi
+
+# Revision that gets built into each binary via the main.version
+# string. Uses the `git describe` output based on the most recent
+# version tag with a short revision suffix or, if nothing has been
+# tagged yet, just the revision.
+#
+# Beware that tags may also be missing in shallow clones as done by
+# some CI systems (like TravisCI, which pulls only 50 commits).
+REV=$(shell git describe --long --tags --match='v*' --dirty 2>/dev/null || git rev-list -n1 HEAD)
+
+# A space-separated list of image tags under which the current build is to be pushed.
+# Determined dynamically.
+IMAGE_TAGS=
+
+# A "canary" image gets built if the current commit is the head of the remote "master" branch.
+# That branch does not exist when building some other branch in TravisCI.
+IMAGE_TAGS+=$(shell if [ "$$(git rev-list -n1 HEAD)" = "$$(git rev-list -n1 origin/master 2>/dev/null)" ]; then echo "canary"; fi)
+
+# A "X.Y.Z-canary" image gets built if the current commit is the head of a "origin/release-X.Y.Z" branch.
+# The actual suffix does not matter, only the "release-" prefix is checked.
+IMAGE_TAGS+=$(shell git branch -r --points-at=HEAD | grep 'origin/release-' | grep -v -e ' -> ' | sed -e 's;.*/release-\(.*\);\1-canary;')
+
+# A release image "vX.Y.Z" gets built if there is a tag of that format for the current commit.
+# --abbrev=0 suppresses long format, only showing the closest tag.
+IMAGE_TAGS+=$(shell tagged="$$(git describe --tags --match='v*' --abbrev=0)"; if [ "$$tagged" ] && [ "$$(git rev-list -n1 HEAD)" = "$$(git rev-list -n1 $$tagged)" ]; then echo $$tagged; fi)
+
+# Images are named after the command contained in them.
+IMAGE_NAME=$(REGISTRY_NAME)/$*
+
+ifdef V
+TESTARGS = -v -args -alsologtostderr -v 5
+else
+TESTARGS =
+endif
+
+build-%:
+	mkdir -p bin
+	CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-X main.version=$(REV) -extldflags "-static"' -o ./bin/$* ./cmd/$*
+
+container-%: build-%
+	docker build -t $*:latest -f $(shell if [ -e ./cmd/$*/Dockerfile ]; then echo ./cmd/$*/Dockerfile; else echo Dockerfile; fi) --label revision=$(REV) .
+
+push-%: container-%
+	set -ex; \
+	push_image () { \
+		docker tag $*:latest $(IMAGE_NAME):$$tag; \
+		docker push $(IMAGE_NAME):$$tag; \
+	}; \
+	for tag in $(IMAGE_TAGS); do \
+		if echo $$tag | grep -q -e '-canary$$'; then \
+			: "creating or overwriting canary image"; \
+			push_image; \
+		elif docker pull $(IMAGE_NAME):$$tag 2>&1 | tee /dev/stderr | grep -q "manifest for $(IMAGE_NAME):$$tag not found"; then \
+			: "creating release image"; \
+			push_image; \
+		else \
+			: "release image $(IMAGE_NAME):$$tag already exists, skipping push"; \
+		fi; \
+	done
+
+build: $(CMDS:%=build-%)
+container: $(CMDS:%=container-%)
+push: $(CMDS:%=push-%)
+
+clean:
+	-rm -rf bin
+
+test:
+	go test `go list ./... | grep -v 'vendor'` $(TESTARGS)
+	go vet `go list ./... | grep -v vendor`
+	files=$$(find . -name '*.go' | grep -v './vendor'); \
+	if [ $$(gofmt -d $$files | wc -l) -ne 0 ]; then \
+		echo "formatting errors:"; \
+		gofmt -d $$files; \
+		false; \
+	fi

travis.yml

@@ -0,0 +1,14 @@
+language: go
+sudo: required
+services:
+  - docker
+matrix:
+  include:
+  - go: 1.11.1
+script:
+- make all test
+after_success:
+  - if [ "${TRAVIS_PULL_REQUEST}" == "false" ]; then
+      docker login -u "${DOCKER_USERNAME}" -p "${DOCKER_PASSWORD}" quay.io;
+      make push;
+    fi