Improve documentation and development tooling (#112)

* Improve badges and add Makefile help * Add a CI step to check if everything generated properly * Remove 0.8 docs * Update README.md * Track tool dependencies in go.mod * Fix generation issues * Simplify development setup * Fix linter discovered issues
meltwater · Apr 11, 2020 · 3172b74 · 3172b74
1 parent 4bc198e
commit 3172b74
Show file tree

Hide file tree

Showing 18 changed files with 433 additions and 347 deletions.
diff --git a/.drone.yml b/.drone.yml
@@ -10,6 +10,11 @@ clone:
   depth: 50
 
 steps:
+# This is needed for the tags. And the tags are needed to determine version.
+- name: fetch
+  image: docker:git
+  commands:
+  - git fetch --tags
 - name: configure-buckets
   image: minio/mc:RELEASE.2018-09-26T00-42-43Z
   commands:
@@ -48,6 +53,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
+  - env -i make PATH=$PATH HOME=$HOME PWD=$PWD GOPATH=$GOPATH generate
+  - git diff --exit-code
+
 - name: rebuild-cache
   image: meltwater/drone-cache:dev
   pull: always

diff --git a/.golangci.yml b/.golangci.yml
@@ -18,6 +18,6 @@ linters-settings:
   lll:
     line-length: 120
   funlen:
-    lines: 85
-    statements: 45
+    lines: 70
+    statements: 40
 
diff --git a/Makefile b/Makefile
@@ -1,29 +1,25 @@
 ROOT_DIR              := $(CURDIR)
-SCRIPTS               := $(ROOT_DIR)/scripts
 
-VERSION               := $(strip $(shell [ -d .git ] && git describe --always --tags --dirty))
+VERSION               := $(strip $(shell [ -d .git ] && git describe --abbrev=0))
+LONG_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)
 
-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
+GOBUILD               := go build -mod=vendor -tags netgo
+GOINSTALL             := go install -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)'
+
+BIN_DIR               ?= $(ROOT_DIR)/tmp/bin
 
-GOLANGCI_LINT_VERSION  = v1.21.0
-GOLANGCI_LINT_BIN      = $(GOBIN)/golangci-lint
-EMBEDMD_BIN            = $(GOBIN)/embedmd
-GOTEST_BIN             = $(GOBIN)/gotest
-GORELEASER_VERSION     = v0.131.1
-GORELEASER_BIN         = $(GOBIN)/goreleaser
-LICHE_BIN              = $(GOBIN)/liche
+GOLANGCI_LINT_BIN      = $(BIN_DIR)/golangci-lint
+EMBEDMD_BIN            = $(BIN_DIR)/embedmd
+GOTEST_BIN             = $(BIN_DIR)/gotest
+LICHE_BIN              = $(BIN_DIR)/liche
 
 UPX                   := upx
 
@@ -32,8 +28,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),,@)
@@ -45,39 +40,34 @@ all: drone-cache
 
 .PHONY: setup
 setup: ## Setups dev environment
-setup: ; $(info $(M) running setup )
-	$(Q) $(SCRIPTS)/setup_dev_environment.sh
+setup: vendor ; $(info $(M) running setup for development )
+	$(Q) make $(GOTEST_BIN) $(EMBEDMD_BIN) $(LICHE_BIN) $(GOLANGCI_LINT_BIN)
 
 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 .
-
-.PHONY: release
-release: ## Release dron-cache
-release: drone-cache $(GORELEASER_BIN) ; $(info $(M) running release )
-	$(Q) $(GORELEASER_BIN) release --rm-dist
-
-.PHONY: snapshot
-snapshot: ## Creates snapshot release without publishing it
-snapshot: drone-cache $(GORELEASER_BIN); $(info $(M) running snapshot )
-	$(Q) $(GORELEASER_BIN) release --skip-publish --rm-dist --snapshot
+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: clean
 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 +81,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 +100,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,28 +151,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
-
-$(GOLANGCI_LINT_BIN): ; $(info $(M) getting golangci-lint )
-	$(Q) curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/$(GOLANGCI_LINT_VERSION)/install.sh \
-		| sed -e '/install -d/d' \
-		| sh -s -- -b $(GOBIN) $(GOLANGCI_LINT_VERSION)
-
-$(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)
+	$(Q) $(GOBUILD) -o $@ github.com/campoy/embedmd
 
 $(LICHE_BIN): ; $(info $(M) getting liche )
-	$(Q) GO111MODULE=on $(GOGET) -u github.com/raviqqe/liche
+	$(Q) $(GOBUILD) -o $@ github.com/raviqqe/liche
+
+$(GOLANGCI_LINT_BIN): ; $(info $(M) getting golangci-lint )
+	$(Q) $(GOBUILD) -o $@ github.com/golangci/golangci-lint/cmd/golangci-lint
diff --git a/README.md b/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
 
 COMMANDS:
    help, h  Shows a list of commands or help for one command
@@ -217,32 +218,30 @@ $ 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
+  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 +274,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
 

diff --git a/archive/tar/tar.go b/archive/tar/tar.go
@@ -125,7 +125,9 @@ func relative(parent string, path string) (string, error) {
 	for strings.HasPrefix(rel, "../") {
 		rel = strings.TrimPrefix(rel, "../")
 	}
+
 	rel = filepath.ToSlash(rel)
+
 	return strings.TrimPrefix(filepath.Join(rel, name), "/"), nil
 }
 

diff --git a/cache/cache.go b/cache/cache.go
@@ -50,8 +50,10 @@ func New(logger log.Logger, s storage.Storage, a archive.Archive, g key.Generato
 	}
 
 	return &cache{
-		NewRebuilder(log.With(logger, "component", "rebuilder"), s, a, g, options.fallbackGenerator, options.namespace, options.override),
-		NewRestorer(log.With(logger, "component", "restorer"), s, a, g, options.fallbackGenerator, options.namespace),
+		NewRebuilder(log.With(logger, "component", "rebuilder"), s, a, g,
+			options.fallbackGenerator, options.namespace, options.override),
+		NewRestorer(log.With(logger, "component", "restorer"), s, a, g,
+			options.fallbackGenerator, options.namespace),
 		NewFlusher(log.With(logger, "component", "flusher"), s, time.Hour),
 	}
 }