src: Makefile developer accessibility (#428)

* ci: increase dns update max retries

* src: Makefile accessibility

Restructures the Makefile for better readibility
Separates core unit tests from template unit tests
Adds a `help` target highlighting core targets
Removes unused 'cluser' and 'release' targets
Removes unused targets

.github/workflows/ci.yaml

@@ -29,10 +29,14 @@ jobs:
         run: |
           curl -s -L -o pkger.tgz ${{ steps.pkger-download-url.outputs.result }}
           tar xvzf pkger.tgz
-      - name: Test
+      - name: Unit Test
         run:  make test
         env:
           PKGER: "./${{ steps.pkger-binaries.outputs.binary }}"
+      - name: Template Unit Tests
+        run:  make test-templates
+        env:
+          PKGER: "./${{ steps.pkger-binaries.outputs.binary }}"
       - name: Lint
         run: make check
     outputs:

.github/workflows/pull_requests.yaml

@@ -59,10 +59,14 @@ jobs:
           curl -s -L -o pkger.tgz ${{ steps.pkger-download-url.outputs.result }}
           tar xvzf pkger.tgz
 
-      - name: Test
+      - name: Unit Test
         run:  make test
         env:
           PKGER: "./${{ steps.pkger-binaries.outputs.binary }}"
+      - name: Template Unit Tests
+        run:  make test-templates
+        env:
+          PKGER: "./${{ steps.pkger-binaries.outputs.binary }}"
       - name: Build
         run:  make build
         env:
@@ -92,7 +96,7 @@ jobs:
       - name: Allocate Cluster
         run: ./hack/allocate.sh
       - name: Local Registry Routing
-        run: ./hack/ci.sh
+        run: ./hack/registry.sh
       - name: Verify Configuration
         run: ./hack/test.sh
       - name: Integration Test Podman
@@ -139,11 +143,11 @@ jobs:
       - name: Allocate Cluster
         run: ./hack/allocate.sh
       - name: Local Registry an Routes (CI)
-        run: ./hack/ci.sh
+        run: ./hack/registry.sh
       - name: Verify Configuration
         run: ./hack/test.sh
       - name: E2E Test
-        run: ./test/run_e2e_test.sh   # by default runs e2e + 'node' specific tests
+        run: make test-e2e
       #- name: E2E Test Go
       #  run: ./test/run_e2e_test.sh go
       #- name: E2E Test Python

Makefile

@@ -1,111 +1,150 @@
-REPO := quay.io/boson/func
-BIN  := func
+# ##
+#
+# Run 'make help' for a summary
+#
+# ##
 
-PKGER?=pkger
+# Binaries
+BIN         := func
+BIN_DARWIN  ?= $(BIN)_darwin_amd64
+BIN_LINUX   ?= $(BIN)_linux_amd64
+BIN_WINDOWS ?= $(BIN)_windows_amd64.exe
 
-DARWIN=$(BIN)_darwin_amd64
-LINUX=$(BIN)_linux_amd64
-WINDOWS=$(BIN)_windows_amd64.exe
+# Version
+# A verbose version is built into the binary including a date stamp, git commit
+# hash and the version tag of the current commit (semver) if it exists.
+# If the current commit does not have a semver tag, 'tip' is used.
+DATE    := $(shell date -u +"%Y%m%dT%H%M%SZ")
+HASH    := $(shell git rev-parse --short HEAD 2>/dev/null)
+VTAG    := $(shell git tag --points-at HEAD)
+VERS    ?= $(shell [ -z $(VTAG) ] && echo 'tip' || echo $(VTAG) )
+LDFLAGS := "-X main.date=$(DATE) -X main.vers=$(VERS) -X main.hash=$(HASH)"
 
+# Templates
+# Built into the binary are the contents of ./templates.  This is done by
+# running 'pkger' which generates pkged.go, containing a go-encoded version of
+# the templates directory.
+PKGER           ?= pkger
+
+# Code is all go source files, used for build target freshness checks
 CODE := $(shell find . -name '*.go')
-DATE := $(shell date -u +"%Y%m%dT%H%M%SZ")
-HASH := $(shell git rev-parse --short HEAD 2>/dev/null)
-VTAG := $(shell git tag --points-at HEAD)
-# a VERS environment variable takes precedence over git tags
-# and is necessary with release-please-action which tags asynchronously
-# unless explicitly, synchronously tagging as is done in ci.yaml
-VERS ?= $(shell [ -z $(VTAG) ] && echo 'tip' || echo $(VTAG) )
 
-TEMPLATE_DIRS=$(shell find templates -type d)
-TEMPLATE_FILES=$(shell find templates -type f -name '*')
-TEMPLATE_PACKAGE=pkged.go
+all: build
+	# Run 'make help' for make target documentation.
 
-build: all
-all: $(TEMPLATE_PACKAGE) $(BIN)
+# Print Help Text
+help:
+	@echo 'Usage: make <OPTIONS> ... <TARGETS>'
+	@echo ''
+	@echo 'Available targets are:'
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
-$(TEMPLATE_PACKAGE): templates $(TEMPLATE_DIRS) $(TEMPLATE_FILES)
-  # ensure no cached dependencies are added to the binary
-	rm -rf templates/node/events/node_modules
-	rm -rf templates/node/http/node_modules
-	rm -rf templates/python/events/__pycache__
-	rm -rf templates/python/http/__pycache__
-	rm -rf templates/typescript/events/node_modules
-	rm -rf templates/typescript/http/node_modules
-	rm -rf templates/rust/events/target
-	rm -rf templates/rust/http/target
-	# to install pkger:  go get github.com/markbates/pkger/cmd/pkger
-	$(PKGER)
+###############
+# Development #
+###############
 
-cross-platform: $(TEMPLATE_PACKAGE) $(DARWIN) $(LINUX) $(WINDOWS)
+##@ Development
 
-darwin: $(DARWIN) ## Build for Darwin (macOS)
+build: $(CODE) ## (default) Build binary for current OS
+	env CGO_ENABLED=0 go build -ldflags $(LDFLAGS) ./cmd/$(BIN)
 
-linux: $(LINUX) ## Build for Linux
-
-windows: $(WINDOWS) ## Build for Windows
-
-$(BIN): $(CODE)  ## Build using environment defaults
-	env CGO_ENABLED=0 go build -ldflags "-X main.date=$(DATE) -X main.vers=$(VERS) -X main.hash=$(HASH)" ./cmd/$(BIN)
-
-$(DARWIN):
-	env CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o $(DARWIN) -ldflags "-X main.date=$(DATE) -X main.vers=$(VERS) -X main.hash=$(HASH)" ./cmd/$(BIN)
-
-$(LINUX):
-	env CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o $(LINUX) -ldflags "-X main.date=$(DATE) -X main.vers=$(VERS) -X main.hash=$(HASH)" ./cmd/$(BIN)
-
-$(WINDOWS):
-	env CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o $(WINDOWS) -ldflags "-X main.date=$(DATE) -X main.vers=$(VERS) -X main.hash=$(HASH)" ./cmd/$(BIN)
-
-test: test-binary test-node test-python test-quarkus test-go test-typescript test-rust
-
-test-binary:
+test: $(CODE) ## Run core unit tests
 	go test -race -cover -coverprofile=coverage.out ./...
 
-test-node:
-	cd templates/node/events && npm ci && npm test && rm -rf node_modules
-	cd templates/node/http && npm ci && npm test && rm -rf node_modules
-
-test-typescript:
-	cd templates/typescript/events && npm ci && npm test && rm -rf node_modules build
-	cd templates/typescript/http && npm ci && npm test && rm -rf node_modules build
-
-test-python:
-	cd templates/python/events && pip3 install -r requirements.txt && python3 test_func.py
-	cd templates/python/http && python3 test_func.py
-
-test-quarkus:
-	cd templates/quarkus/events && mvn test && mvn clean
-	cd templates/quarkus/http && mvn test && mvn clean
-
-test-go:
-	cd templates/go/events && go test
-	cd templates/go/http && go test
-
-test-rust:
-	cd templates/rust/events && cargo test && cargo clean
-	cd templates/rust/http && cargo test && cargo clean
-
-test-integration:
-	go test -tags integration ./... -v
+check: bin/golangci-lint ## Check code quality (lint)
+	./bin/golangci-lint run --timeout 300s
+	cd test/_e2e && ../../bin/golangci-lint run --timeout 300s
 
 bin/golangci-lint:
 	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b ./bin v1.40.1
 
-check: bin/golangci-lint
-	./bin/golangci-lint run --timeout 300s
-	cd test/_e2e && ../../bin/golangci-lint run --timeout 300s
-
-release: build test
-	go get -u github.com/git-chglog/git-chglog/cmd/git-chglog
-	git-chglog --next-tag $(VTAG) -o CHANGELOG.md
-	git commit -am "release: $(VTAG)"
-	git tag $(VTAG)
-
-cluster: ## Set up a local cluster for integraiton tests.
-	# Creating KinD cluster `kind`.
-	# Delete with ./hack/delete.sh
-	./hack/allocate.sh && ./hack/configure.sh
-
-clean:
-	rm -f $(BIN) $(WINDOWS) $(LINUX) $(DARWIN)
+clean: ## Remove generated artifacts such as binaries
+	rm -f $(BIN) $(BIN_WINDOWS) $(BIN_LINUX) $(BIN_DARWIN)
 	-rm -f coverage.out
+
+clean-templates: 
+	# Clearing caches in ./templates
+	@rm -rf templates/node/events/node_modules
+	@rm -rf templates/node/http/node_modules
+	@rm -rf templates/python/events/__pycache__
+	@rm -rf templates/python/http/__pycache__
+	@rm -rf templates/typescript/events/node_modules
+	@rm -rf templates/typescript/http/node_modules
+	@rm -rf templates/rust/events/target
+	@rm -rf templates/rust/http/target
+
+################
+# Templates #
+################
+
+##@ Builtin Language Packs
+
+templates: test-templates pkged.go ## Run template unit tests and update pkged.go
+
+pkged.go: clean-templates
+	# Encoding ./templates as pkged.go (requires 'pkger':  go get github.com/markbates/pkger/cmd/pkger)
+	$(PKGER)
+
+test-templates: test-go test-node test-python test-quarkus test-rust test-typescript ## Run all template tests
+
+test-go: ## Test Go templates
+	cd templates/go/events && go test
+	cd templates/go/http && go test
+
+test-node: ## Test Node templates
+	cd templates/node/events && npm ci && npm test && rm -rf node_modules
+	cd templates/node/http && npm ci && npm test && rm -rf node_modules
+
+test-python: ## Test Python templates
+	cd templates/python/events && pip3 install -r requirements.txt && python3 test_func.py
+	cd templates/python/http && python3 test_func.py
+
+test-quarkus: ## Test Quarkus templates
+	cd templates/quarkus/events && mvn test && mvn clean
+	cd templates/quarkus/http && mvn test && mvn clean
+
+test-rust: ## Test Rust templates
+	cd templates/rust/events && cargo test && cargo clean
+	cd templates/rust/http && cargo test && cargo clean
+
+test-typescript: ## Test Typescript templates
+	cd templates/typescript/events && npm ci && npm test && rm -rf node_modules build
+	cd templates/typescript/http && npm ci && npm test && rm -rf node_modules build
+
+
+###################
+# Release Testing #
+###################
+
+##@ Extended Testing (cluster required)
+
+test-integration: ## Run integration tests using an available cluster.
+	go test -tags integration ./... -v
+
+test-e2e: ## Run end-to-end tests using an available cluster.
+	./test/run_e2e_test.sh
+
+
+######################
+# Release Artifacts  #
+######################
+
+##@ Release Artifacts
+
+cross-platform: darwin linux windows ## Build all distributable (cross-platform) binaries
+
+darwin: $(BIN_DARWIN) ## Build for Darwin (macOS)
+
+$(BIN_DARWIN): pkged.go
+	env CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o $(BIN_DARWIN) -ldflags $(LDFLAGS) ./cmd/$(BIN)
+
+linux: $(BIN_LINUX) ## Build for Linux
+
+$(BIN_LINUX): pkged.go
+	env CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o $(BIN_LINUX) -ldflags $(LDFLAGS) ./cmd/$(BIN)
+
+windows: $(BIN_WINDOWS) ## Build for Windows
+
+$(BIN_WINDOWS): pkged.go
+	env CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o $(BIN_WINDOWS) -ldflags $(LDFLAGS) ./cmd/$(BIN)
+

hack/allocate.sh

@@ -90,7 +90,7 @@ serving() {
 dns() {
   echo "${em}③ DNS${me}"
 
-  i=0; n=3
+  i=0; n=10
   while :; do
     kubectl patch configmap/config-domain \
     --namespace knative-serving \
@@ -103,7 +103,7 @@ dns() {
       exit 1
     fi
     echo 'Retrying...'
-    sleep 2
+    sleep 5
   done
 }
 

hack/registry.sh

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 
 # 
-# CI-specific configuration for linux systems.
-# Patches docker to allow the local kind registtry without authentication.
-# Adds the registry to the local hosts file
-# Restarts the internal webkook (fix).
+# Set up local registry (linux only)
+# - Registers registry with Docker as trusted
+# - Adds 'kind-rgistry' to /etc/hosts
 #
 
 set -o errexit