chore: improve makefile

Makefile

@@ -2,24 +2,30 @@
 
 export PATH := $(abspath bin/):${PATH}
 
-# Dependency versions
-GOLANGCI_VERSION = 1.54.2
-LICENSEI_VERSION = 0.8.0
+##@ General
+
+# Targets commented with ## will be visible in "make help" info.
+# Comments marked with ##@ will be used as categories for a group of targets.
+
+.PHONY: help
+default: 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)
+
+##@ Development
 
 .PHONY: up
 up: ## Start development environment
 	docker compose up -d
 
-.PHONY: stop
-stop: ## Stop development environment
-	docker compose stop
-
 .PHONY: down
 down: ## Destroy development environment
 	docker compose down -v
 
+##@ Checks
+
 .PHONY: check
-check: test lint ## Run checks (tests and linters)
+check: lint test ## Run lint checks and tests
 
 .PHONY: test
 test: ## Run tests
@@ -31,33 +37,44 @@ lint: ## Run linters
 
 .PHONY: lint-go
 lint-go:
-	golangci-lint run $(if ${CI},--out-format github-actions,)
+	$(GOLANGCI_LINT_BIN) run $(if ${CI},--out-format github-actions,)
 
 .PHONY: lint-yaml
 lint-yaml:
 	yamllint $(if ${CI},-f github,) --no-warnings .
 
+.PHONY: license-check
+license-check: ## Run license check
+	$(LICENSEI_BIN) check
+	$(LICENSEI_BIN) header
+
 .PHONY: fmt
 fmt: ## Format code
-	golangci-lint run --fix
+	$(GOLANGCI_LINT_BIN) run --fix
 
-.PHONY: license-check
-license-check: ## Run license check
-	licensei check
-	licensei header
+##@ Dependencies
 
 deps: bin/golangci-lint bin/licensei
 deps: ## Install dependencies
 
+# Dependency versions
+GOLANGCI_VERSION = 1.54.2
+LICENSEI_VERSION = 0.8.0
+
+# Dependency binaries
+GOLANGCI_LINT_BIN := golangci-lint
+LICENSEI_BIN := licensei
+
+# If we have "bin" dir, use those binaries instead
+ifneq ($(wildcard ./bin/.),)
+	GOLANGCI_LINT_BIN := bin/$(GOLANGCI_LINT_BIN)
+	LICENSEI_BIN := bin/$(LICENSEI_BIN)
+endif
+
 bin/golangci-lint:
 	@mkdir -p bin
 	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | bash -s -- v${GOLANGCI_VERSION}
 
 bin/licensei:
 	@mkdir -p bin
 	curl -sfL https://raw.githubusercontent.com/goph/licensei/master/install.sh | bash -s -- v${LICENSEI_VERSION}
-
-.PHONY: help
-.DEFAULT_GOAL := help
-help:
-	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-10s\033[0m %s\n", $$1, $$2}'

README.md

@@ -3,7 +3,7 @@
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/bank-vaults/internal/ci.yaml?branch=main&style=flat-square)](https://github.com/bank-vaults/internal/actions/workflows/ci.yaml?query=workflow%3ACI)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/bank-vaults/vault-env/badge?style=flat-square)](https://api.securityscorecards.dev/projects/github.com/bank-vaults/internal)
 
-**Libraries used internally by Bank-Vaults components.**
+**Internal libraries used by Bank-Vaults components.**
 
 ## Development
 
@@ -13,6 +13,12 @@ _Alternatively, install [Go](https://go.dev/dl/) on your computer then run `make
 
 Make sure Docker is installed with Compose.
 
+Fetch required tools:
+
+```shell
+make deps
+```
+
 Run project dependencies:
 
 ```shell
@@ -37,13 +43,9 @@ Some linter violations can automatically be fixed:
 make fmt
 ```
 
-Once you are done either stop or tear down dependencies:
+Once you are done, you can tear down project dependencies:
 
 ```shell
-make stop
-
-# OR
-
 make down
 ```