chore(build): make it easier to use makefile (pun intended)

.github/workflows/nightly.yml

@@ -34,8 +34,8 @@ jobs:
 
     - name: Build images
       run: |
-        make docker-nightly-build
+        make nightly-build
 
     - name: Push images
       run: |
-        make docker-nightly-push
+        make nightly-push

.github/workflows/publish-release.yml

@@ -122,8 +122,8 @@ jobs:
 
     - name: Build images
       run: |
-        make docker-all
+        make build-docker-all
     
     - name: Push images
       run: |
-        make docker-push-all
+        make push-docker-all

Makefile

@@ -1,3 +1,29 @@
+#!/usr/bin/env bash
+
+#
+# Makefile with some common workflow for dev, build and test
+#
+
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk command is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+# The following help command is Licensed under the Apache License, Version 2.0 (the "License")
+# Copyright 2023 The Kubernetes Authors.
+.PHONY: help
+help: ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+
 GO ?= go
 GOLANGCILINT ?= golangci-lint
 
@@ -20,24 +46,10 @@ ifeq ($(COVER),true)
 TESTCOVER ?= -coverprofile c.out
 endif
 
-.PHONY: all
-all: lint $(BINARY)
-
-.PHONY: clean
-clean:
-	-rm -rf release
-	-rm -f $(BINARY)
-
-.PHONY: distclean
-distclean: clean
-	rm -rf vendor
-
-.PHONY: lint
-lint: validate-go-version
-	GO111MODULE=on $(GOLANGCILINT) run
+##@ Build
 
 .PHONY: build
-build: validate-go-version clean $(BINARY)
+build: validate-go-version clean $(BINARY) ## Build and create oauth2-proxy binary from current source code
 
 $(BINARY):
 	CGO_ENABLED=0 $(GO) build -a -installsuffix cgo -ldflags="-X github.com/oauth2-proxy/oauth2-proxy/v7/pkg/version.VERSION=${VERSION}" -o $@ github.com/oauth2-proxy/oauth2-proxy/v7
@@ -56,60 +68,92 @@ DOCKER_BUILDX_ARGS_ALPINE            ?= --build-arg RUNTIME_IMAGE=${DOCKER_BUILD
 DOCKER_BUILDX_X_PLATFORM_ALPINE      := docker buildx build ${DOCKER_BUILDX_ARGS_ALPINE} --platform ${DOCKER_BUILD_PLATFORM_ALPINE}
 DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE := $(DOCKER_BUILDX_X_PLATFORM_ALPINE) --push
 
-.PHONY: docker
-docker:
+.PHONY: build-docker
+build-docker: build-distroless build-alpine ## Build docker image for local platform architecture in both flavours (distroless / alpine)
+
+.PHONY: build-distroless
+build-distroless: ## Build single distroless based docker image for all platform architectures
 	$(DOCKER_BUILDX_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
-	$(DOCKER_BUILDX_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
 
-.PHONY: docker-push
-docker-push:
-	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
-	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
+.PHONY: build-alpine
+build-alpine: ## Build single alpine based docker image for all platform architectures
+	$(DOCKER_BUILDX_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
 
-.PHONY: docker-all
-docker-all: docker
+.PHONY: build-docker-all
+build-docker-all: build-docker ## Build docker images for all supported architectures in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX) --platform linux/amd64   -t $(REGISTRY)/$(REPOSITORY):latest-amd64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-amd64 .
 	$(DOCKER_BUILDX) --platform linux/arm64   -t $(REGISTRY)/$(REPOSITORY):latest-arm64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-arm64 .
 	$(DOCKER_BUILDX) --platform linux/ppc64le -t $(REGISTRY)/$(REPOSITORY):latest-ppc64le -t $(REGISTRY)/$(REPOSITORY):${VERSION}-ppc64le .
 	$(DOCKER_BUILDX) --platform linux/arm/v7  -t $(REGISTRY)/$(REPOSITORY):latest-armv7   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-armv7 .
 	$(DOCKER_BUILDX) --platform linux/s390x   -t $(REGISTRY)/$(REPOSITORY):latest-s390x -t $(REGISTRY)/$(REPOSITORY):${VERSION}-s390x .
 
-.PHONY: docker-push-all
-docker-push-all: docker-push
+
+##@ Publish
+
+.PHONY: push-docker
+push-docker: push-distroless push-alpine ## Push multi architecture docker images for both flavours (distroless / alpine)
+
+.PHONY: push-distroless
+push-distroless: ## Push multi architecture distroless based docker image
+	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
+
+.PHONY: push-alpine
+push-alpine: ## Push multi architecture alpine based docker image
+	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
+
+.PHONY: push-docker-all
+push-docker-all: push-docker ## Push docker images for all supported architectures in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_PUSH) --platform linux/amd64   -t $(REGISTRY)/$(REPOSITORY):latest-amd64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-amd64 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/arm64   -t $(REGISTRY)/$(REPOSITORY):latest-arm64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-arm64 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/ppc64le -t $(REGISTRY)/$(REPOSITORY):latest-ppc64le -t $(REGISTRY)/$(REPOSITORY):${VERSION}-ppc64le .
 	$(DOCKER_BUILDX_PUSH) --platform linux/arm/v7  -t $(REGISTRY)/$(REPOSITORY):latest-armv7   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-armv7 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/s390x   -t $(REGISTRY)/$(REPOSITORY):latest-s390x -t $(REGISTRY)/$(REPOSITORY):${VERSION}-s390x .
 
-.PHONY: docker-nightly-build
-docker-nightly-build:
+
+##@ Nightly scheduling
+
+.PHONY: nightly-build
+nightly-build: ## Nightly build command for docker images in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY)-nightly:latest -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE} .
 	$(DOCKER_BUILDX_X_PLATFORM_ALPINE) -t ${REGISTRY}/$(REPOSITORY)-nightly:latest-alpine -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE}-alpine .
 
-.PHONY: docker-nightly-push
-docker-nightly-push:
+.PHONY: nightly-push
+nightly-push: ## Nightly push command for docker images in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY)-nightly:latest -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE} .
 	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t ${REGISTRY}/$(REPOSITORY)-nightly:latest-alpine -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE}-alpine .
 
+
+##@ Docs
+
 .PHONY: generate
-generate:
+generate: ## Generate alpha config docs from golang structs
 	go generate ./pkg/...
 
 .PHONY: verify-generate
-verify-generate: generate
+verify-generate: generate ## Verify command to check if alpha config docs are in line with golang struct changes
 	git diff --exit-code
 
+##@ Miscellaneous
+
 .PHONY: test
-test: lint
+test: lint ## Run all Go tests
 	GO111MODULE=on $(GO) test $(TESTCOVER) -v -race ./...
 
 .PHONY: release
-release: validate-go-version lint test
+release: validate-go-version lint test ## Create a full release for all architectures (binaries and checksums)
 	BINARY=${BINARY} VERSION=${VERSION} ./dist.sh
 
+.PHONY: clean
+clean: ## Cleanup release and build files
+	-rm -rf release
+	-rm -f $(BINARY)
+
+.PHONY: lint
+lint: validate-go-version ## Lint all files using golangci-lint
+	GO111MODULE=on $(GOLANGCILINT) run
+
 .PHONY: validate-go-version
-validate-go-version:
+validate-go-version: ## Validate Go environment requirements
 	@if [ $(GO_MAJOR_VERSION) -gt $(MINIMUM_SUPPORTED_GO_MAJOR_VERSION) ]; then \
 		exit 0 ;\
 	elif [ $(GO_MAJOR_VERSION) -lt $(MINIMUM_SUPPORTED_GO_MAJOR_VERSION) ]; then \
@@ -120,12 +164,3 @@ validate-go-version:
 		exit 1; \
 	fi
 
-# local-env can be used to interact with the local development environment
-# eg:
-#    make local-env-up          # Bring up a basic test environment
-#    make local-env-down        # Tear down the basic test environment
-#    make local-env-nginx-up    # Bring up an nginx based test environment
-#    make local-env-nginx-down  # Tead down the nginx based test environment
-.PHONY: local-env-%
-local-env-%:
-	make -C contrib/local-environment $*

RELEASE.md

@@ -41,8 +41,8 @@ Note this uses `v4.1.0` as an example release number.
 10. Publish release in Github
 11. Make and push docker images to Quay
   ```
-  make docker-all
-  make docker-push-all
+  make build-docker-all
+  make push-docker-all
   ```
   Note: Ensure the docker tags don't include `-dirty`. This means you have uncommitted changes.