Improve documentation and development tooling

.drone.yml

@@ -48,6 +48,13 @@ steps:
   - name: testdata
     path: /drone/src/tmp/testdata/cache
 
+- name: generate
+  image: golang:1.14.1-alpine3.11
+  commands:
+  - apk add --update make git
+  - make generate
+  - git diff --exit-code
+
 - name: rebuild-cache
   image: meltwater/drone-cache:dev
   pull: always

Makefile

@@ -3,20 +3,20 @@ SCRIPTS               := $(ROOT_DIR)/scripts
 
 VERSION               := $(strip $(shell [ -d .git ] && git describe --always --tags --dirty))
 BUILD_DATE            := $(shell date -u +"%Y-%m-%dT%H:%M:%S%Z")
-VCS_REF               := $(strip $(shell [ -d .git ] && git rev-parse --short HEAD))
+VCS_REF               := $(strip $(shell [ -d .git ] && git rev-parse HEAD))
 
 GO_PACKAGES            = $(shell go list ./... | grep -v -E '/vendor/|/test')
 GO_FILES              := $(shell find . -name \*.go -print)
 
+GOBUILD               := go build -mod=vendor -tags netgo
+GOMOD                 := go mod
+GOFMT                 := gofmt
+
+LDFLAGS               := '-s -w -X main.version=$(VERSION) -X main.commit=$(VCS_REF) -X main.date=$(BUILD_DATE)'
+
 GOPATH                := $(firstword $(subst :, ,$(shell go env GOPATH)))
 GOBIN                 := $(GOPATH)/bin
 
-GOCMD                 := go
-GOBUILD               := $(GOCMD) build -mod=vendor -tags netgo
-GOMOD                 := $(GOCMD) mod
-GOGET                 := $(GOCMD) get
-GOFMT                 := gofmt
-
 GOLANGCI_LINT_VERSION  = v1.21.0
 GOLANGCI_LINT_BIN      = $(GOBIN)/golangci-lint
 EMBEDMD_BIN            = $(GOBIN)/embedmd
@@ -32,8 +32,7 @@ DOCKER_BUILD          := $(DOCKER) build
 DOCKER_PUSH           := $(DOCKER) push
 DOCKER_COMPOSE        := docker-compose
 
-
-DOCKER_REPO           :=  meltwater/drone-cache
+CONTAINER_REPO        :=  meltwater/drone-cache
 
 V                      = 0
 Q                      = $(if $(filter 1,$V),,@)
@@ -50,12 +49,12 @@ setup: ; $(info $(M) running setup )
 
 drone-cache: ## Runs drone-cache target
 drone-cache: vendor main.go $(wildcard *.go) $(wildcard */*.go) ; $(info $(M) running drone-cache )
-	$(Q) CGO_ENABLED=0 $(GOBUILD) -a -ldflags '-s -w -X main.version=$(VERSION)' -o $@ .
+	$(Q) CGO_ENABLED=0 $(GOBUILD) -a -ldflags $(LDFLAGS) -o $@ .
 
 .PHONY: build
-build: ## Runs build target
-build: main.go $(wildcard *.go) $(wildcard */*.go) ; $(info $(M) running build )
-	$(Q) $(GOBUILD) -ldflags '-X main.version=$(VERSION)' -o drone-cache .
+build: ## Runs build target, always builds
+build: vendor main.go $(wildcard *.go) $(wildcard */*.go) ; $(info $(M) running build )
+	$(Q) CGO_ENABLED=0 $(GOBUILD) -ldflags $(LDFLAGS) -o drone-cache .
 
 .PHONY: release
 release: ## Release dron-cache
@@ -72,12 +71,17 @@ clean: ## Cleans build resourcess
 clean: ; $(info $(M) running clean )
 	$(Q) rm -f drone-cache
 	$(Q) rm -rf target
+	$(Q) rm -rf tmp
 
 tmp/help.txt: drone-cache
-	mkdir -p tmp
+	-mkdir -p tmp
 	$(ROOT_DIR)/drone-cache --help &> tmp/help.txt
 
-README.md: tmp/help.txt $(EMBEDMD_BIN)
+tmp/make_help.txt: Makefile
+	-mkdir -p tmp
+	$(Q) awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  %-15s\t %s\n", $$1, $$2 }' $(MAKEFILE_LIST) &> tmp/make_help.txt
+
+README.md: tmp/help.txt tmp/make_help.txt $(EMBEDMD_BIN)
 	$(EMBEDMD_BIN) -w README.md
 
 tmp/docs.txt: drone-cache
@@ -91,6 +95,10 @@ docs: clean README.md DOCS.md $(LICHE_BIN)
 	$(Q) $(LICHE_BIN) --recursive docs --document-root .
 	$(Q) $(LICHE_BIN) --exclude "(goreportcard.com)" --document-root . *.md
 
+generate: ## Generate documentation, website and yaml files,
+generate: docs # site
+	$(Q) echo "Generated!"
+
 .PHONY: vendor
 vendor: ## Updates vendored copy of dependencies
 vendor: ; $(info $(M) running vendor )
@@ -106,13 +114,12 @@ compress: drone-cache ; $(info $(M) running compress )
 .PHONY: container
 container: ## Builds drone-cache docker image with latest tag
 container: release Dockerfile ; $(info $(M) running container )
-	$(Q) $(DOCKER_BUILD) -t $(DOCKER_REPO):dev .
-
+	$(Q) $(DOCKER_BUILD) -t $(CONTAINER_REPO):dev .
 
 .PHONY: container-push
-container-push: ## Pushes latest $(DOCKER_REPO) image to repository
+container-push: ## Pushes latest $(CONTAINER_REPO) image to repository
 container-push: container ; $(info $(M) running container-push )
-	$(Q) $(DOCKER_PUSH) $(DOCKER_REPO):dev
+	$(Q) $(DOCKER_PUSH) $(CONTAINER_REPO):dev
 
 .PHONY: test
 test: ## Runs tests
@@ -158,19 +165,18 @@ format: ; $(info $(M) running format )
 
 .PHONY: help
 help: ## Shows this help message
-	$(Q) echo 'usage: make [target] ...'
-	$(Q) echo
-	$(Q) echo 'targets : '
-	$(Q) echo
-	$(Q) fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'| column -s: -t
+	$(Q) awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m\t %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
 
-### Dependencies
+# Dependencies
 
 $(GOTEST_BIN): ; $(info $(M) getting gotest )
-	$(Q) GO111MODULE=off $(GOGET) -u github.com/rakyll/gotest
+	$(Q) $(GOBUILD) -o $@ github.com/rakyll/gotest
 
 $(EMBEDMD_BIN): ; $(info $(M) getting embedmd )
-	$(Q) GO111MODULE=off $(GOGET) -u github.com/campoy/embedmd
+	$(Q) $(GOBUILD) -o $@ github.com/campoy/embedmd
+
+$(LICHE_BIN): ; $(info $(M) getting liche )
+	$(Q) $(GOBUILD) -o $@ github.com/raviqqe/liche
 
 $(GOLANGCI_LINT_BIN): ; $(info $(M) getting golangci-lint )
 	$(Q) curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/$(GOLANGCI_LINT_VERSION)/install.sh \
@@ -180,6 +186,3 @@ $(GOLANGCI_LINT_BIN): ; $(info $(M) getting golangci-lint )
 $(GORELEASER_BIN): ; $(info $(M) getting goreleaser )
 	$(Q) curl -sfL https://install.goreleaser.com/github.com/goreleaser/goreleaser.sh \
 		| VERSION=$(GORELEASER_VERSION) sh -s -- -b $(GOBIN) $(GORELEASER_VERSION)
-
-$(LICHE_BIN): ; $(info $(M) getting liche )
-	$(Q) GO111MODULE=on $(GOGET) -u github.com/raviqqe/liche

README.md

@@ -1,6 +1,10 @@
 # drone-cache
 
-[![semver](https://img.shields.io/badge/semver-1.0.4-blue.svg?cacheSeconds=2592000)](https://github.com/meltwater/drone-cache/releases) [![Drone](https://cloud.drone.io/api/badges/meltwater/drone-cache/status.svg)](https://cloud.drone.io/meltwater/drone-cache) [![Maintenance](https://img.shields.io/maintenance/yes/2020.svg)](https://github.com/meltwater/drone-cache/commits/master) [![Go Doc](https://godoc.org/github.com/meltwater/drone-cache?status.svg)](http://godoc.org/github.com/meltwater/drone-cache) [![Go Report Card](https://goreportcard.com/badge/github.com/meltwater/drone-cache)](https://goreportcard.com/report/github.com/meltwater/drone-cache) [![codebeat badge](https://codebeat.co/badges/802c6149-ac2d-4514-8648-f618c63a8d9e)](https://codebeat.co/projects/github-com-meltwater-drone-cache-master) [![](https://images.microbadger.com/badges/image/meltwater/drone-cache.svg)](https://microbadger.com/images/meltwater/drone-cache) [![](https://images.microbadger.com/badges/version/meltwater/drone-cache.svg)](https://microbadger.com/images/meltwater/drone-cache)
+[![Latest Release](https://img.shields.io/github/release/meltwater/drone-cache.svg?)](https://github.com/meltwater/drone-cache/releases/latest) [![Maintenance](https://img.shields.io/maintenance/yes/2020.svg)](https://github.com/meltwater/drone-cache/commits/master) ![GitHub](https://img.shields.io/github/license/meltwater/drone-cache) [![Gitter](https://badges.gitter.im/drone-cache/community.svg)](https://gitter.im/drone-cache/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![drone](https://cloud.drone.io/api/badges/meltwater/drone-cache/status.svg)](https://cloud.drone.io/meltwater/drone-cache) ![release](https://github.com/meltwater/drone-cache/workflows/release/badge.svg) ![snapshot](https://github.com/meltwater/drone-cache/workflows/snapshot/badge.svg)
+
+[![Go Doc](https://godoc.org/github.com/meltwater/drone-cache?status.svg)](http://godoc.org/github.com/meltwater/drone-cache) [![Go Code reference](https://img.shields.io/badge/code%20reference-go.dev-darkblue.svg)](https://pkg.go.dev/github.com/meltwater/drone-cache?tab=subdirectories) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2713/badge)](https://bestpractices.coreinfrastructure.org/projects/2713) [![Go Report Card](https://goreportcard.com/badge/github.com/meltwater/drone-cache)](https://goreportcard.com/report/github.com/meltwater/drone-cache) [![codebeat badge](https://codebeat.co/badges/802c6149-ac2d-4514-8648-f618c63a8d9e)](https://codebeat.co/projects/github-com-meltwater-drone-cache-master)
+
+[![meltwater/drone-cache on DockerHub](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/r/meltwater/drone-cache) [![DockerHub Pulls](https://img.shields.io/docker/pulls/meltwater/drone-cache.svg)](https://hub.docker.com/r/meltwater/drone-cache) [![](https://images.microbadger.com/badges/image/meltwater/drone-cache.svg)](https://microbadger.com/images/meltwater/drone-cache) [![](https://images.microbadger.com/badges/version/meltwater/drone-cache.svg)](https://microbadger.com/images/meltwater/drone-cache)
 
 <p align="center"><img src="images/drone_gopher.png" width="400"></p>
 
@@ -46,10 +50,8 @@ With restored dependencies from a cache, commands like `mix deps.get` will only
 
 The following example configuration file (`.drone.yml`) shows the most common use of drone-cache.
 
-Note: These configs use drone 1.0 syntax. If you are using drone 0.8, check the examples in [docs/examples/drone-0.8.md](docs/examples/drone-0.8.md).
-
 [//]: # (TODO: Move to a dedicated directory in docs, per backend!)
-### Simple (Storing the cache in S3)
+### Simple (with AWS S3 backend)
 
 ```yaml
 kind: pipeline
@@ -97,10 +99,9 @@ steps:
 
 ```
 
-### Other Examples
+### More Examples
 
-- examples for Drone 0.8, see [docs/examples/drone-0.8.md](docs/examples/drone-0.8.md)
-- examples for Drone 1.0, see [docs/examples/drone-1.0.md](docs/examples/drone-1.0.md)
+- examples for Drone, see [docs/examples/drone-1.0.md](docs/examples/drone.md)
 
 ## Usage
 
@@ -115,7 +116,7 @@ USAGE:
    drone-cache [global options] command [command options] [arguments...]
 
 VERSION:
-   v1.0.4-36-g97fce2d
+   v1.1.0-rc0-5-g63b3af3-dirty
 
 COMMANDS:
    help, h  Shows a list of commands or help for one command
@@ -217,32 +218,32 @@ $ docker run --rm \
 
 ## Development
 
-### Local set-up
-
-```console
-$ make setup
-```
-
-### Tests
-
-```console
-$ make test
-```
-
-### Build Binary
-
-Build the binary with the following commands:
-
-```console
-$ make build
-```
-
-### Build Docker image
-
-Build the docker image with the following commands:
+[embedmd]:# (tmp/make_help.txt)
+```txt
 
-```console
-$ make container
+Usage:
+  make <target>
+
+Targets:
+  setup          	  Setups dev environment
+  drone-cache    	  Runs drone-cache target
+  build          	  Runs build target, always builds
+  release        	  Release dron-cache
+  snapshot       	  Creates snapshot release without publishing it
+  clean          	  Cleans build resourcess
+  docs           	  Generates docs
+  generate       	  Generate documentation, website and yaml files,
+  vendor         	  Updates vendored copy of dependencies
+  compress       	  Creates compressed binary
+  container      	  Builds drone-cache docker image with latest tag
+  container-push 	  Pushes latest $(CONTAINER_REPO) image to repository
+  test           	  Runs tests
+  test-integration	  Runs integration tests
+  test-unit      	  Runs unit tests
+  lint           	  Runs golangci-lint analysis
+  fix            	  Runs golangci-lint fix
+  format         	  Runs gofmt
+  help           	  Shows this help message
 ```
 
 ## Releases
@@ -275,7 +276,6 @@ See the list of [all contributors](https://github.com/meltwater/drone-cache/grap
 - [github.com/bsm/drone-s3-cache](https://github.com/bsm/drone-s3-cache) (original work)
 - [github.com/Drillster/drone-volume-cache](https://github.com/Drillster/drone-volume-cache)
 - [github.com/drone/drone-cache-lib](https://github.com/drone/drone-cache-lib)
-  > From the version `v1.1.0` and forward, `drone-cache` conforms interfaces from `github.com/drone/drone-cache-lib`, with anticipation of [a future cache plugin interface in the configuration](https://github.com/drone/drone/issues/2060).
 
 ## Contributing