From fa4595e33ea92a43c7288a3a725fcc3f09dc6639 Mon Sep 17 00:00:00 2001
From: Christopher Small <metasoarous@gmail.com>
Date: Mon, 27 Nov 2023 22:49:22 -0800
Subject: [PATCH] improve `make help` output by clarifying config, plus general
 cleanup (#1748)

---
 Makefile | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Makefile b/Makefile
index 09805f304..f2709054a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,9 @@
-## TTD:
-# make start; make stop
-# make PROD start; make PROD stop
-# make TEST start; make TEST stop
-# update TAG
+## Examples:
+# make start                      - runs against main development `.env` file
+# make PROD start                 - runs against `prod.env` config file
+# make TEST e2e                   - runs tests
+# make ENV_FILE=custom.env start  - runs against parameters in `custom.env` config file
+# make build-web-assets           - build and extract web assets
 
 SHELL=/bin/bash
 E2E_RUN = cd e2e;
@@ -12,12 +13,12 @@ export TAG = $(shell grep -e ^TAG ${ENV_FILE} | awk -F'[=]' '{gsub(/ /,""); prin
 export GIT_HASH = $(shell git rev-parse --short HEAD)
 export COMPOSE_FILE_ARGS = -f docker-compose.yml -f docker-compose.dev.yml
 
-PROD: ## Run in prod mode (e.g. `make PROD start`, etc.)
+PROD: ## Run in prod mode (e.g. `make PROD start`, etc.) using config in `prod.env`
 	$(eval ENV_FILE = prod.env)
 	$(eval TAG = $(shell grep -e ^TAG ${ENV_FILE} | awk -F'[=]' '{gsub(/ /,"");print $$2}'))
 	$(eval COMPOSE_FILE_ARGS = -f docker-compose.yml)
 
-TEST: ## Run in test mode (e.g. `make TEST start`, etc.)
+TEST: ## Run in test mode (e.g. `make TEST e2e-run`, etc.) using config in `test.env`
 	$(eval ENV_FILE = test.env)
 	$(eval TAG = $(shell grep -e ^TAG ${ENV_FILE} | awk -F'[=]' '{gsub(/ /,"");print $$2}'))
 	$(eval COMPOSE_FILE_ARGS = -f docker-compose.yml -f docker-compose.test.yml)
@@ -47,7 +48,7 @@ rm-images: echo_vars ## Remove Docker images where (polis_tag="${TAG}")
 	@echo 'removing filtered images (polis_tag="${TAG}")'
 	@-docker rmi -f $(shell docker images -q --filter "label=polis_tag=${TAG}")
 
-rm-ALL: rm-containers rm-volumes rm-images ## Remove Docker containers, volumes, and images where (polis_tag="${TAG}")
+rm-ALL: rm-containers rm-volumes rm-images ## Remove Docker containers, volumes, and images (including db) where (polis_tag="${TAG}")
 	@echo Done.
 
 hash: ## Show current short hash
@@ -65,18 +66,18 @@ start-recreate: echo_vars ## Start all Docker containers with recreated environm
 start-rebuild: echo_vars ## Start all Docker containers, [re]building as needed
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} up --build
 
-start-FULL-REBUILD: echo_vars stop rm-ALL ## Remove and restart all Docker containers, volumes, and images where (polis_tag="${TAG}")
+start-FULL-REBUILD: echo_vars stop rm-ALL ## Remove and restart all Docker containers, volumes, and images (including db), as with rm-ALL
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} build --no-cache
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} down
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} up --build
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} down
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} up --build
 
-build-web-assets: ## Build and extract static web assets for cloud deployment
+build-web-assets: ## Build and extract static web assets for cloud deployment to `build` dir
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} create --build --force-recreate file-server
 	$(MAKE) extract-web-assets
 
-extract-web-assets: ## Extract static web assets from file-server for cloud deployment
+extract-web-assets: ## Extract static web assets from file-server to `build` dir
 	/bin/rm -rf build
 	docker compose ${COMPOSE_FILE_ARGS} --env-file ${ENV_FILE} cp file-server:/app/build/ build
 
@@ -99,15 +100,23 @@ rbs: start-rebuild
 	@true
 
 .PHONY: help pull start stop rm-containers rm-volumes rm-images rm-ALL hash build-no-cache start-rebuild \
-	start-recreate restart-FULL-REBUILD e2e-install e2e-prepare e2e-run-minimal e2e-run-standalone e2e-run-secret \
-	e2e-run-subset e2e-run-all build-web-assets extract-web-assets upload-web-assets
+	start-recreate restart-FULL-REBUILD e2e-install e2e-run e2e-run-all e2e-run-interactive \
+	build-web-assets extract-web-assets
 
 
 help:
 	@echo 'Usage: make <command>'
 	@echo
-	@echo 'where <command> is one of the following:'
+	@echo 'where <command> can be one or more of the following:'
 	@echo
 	@grep -E '^[a-z0-9A-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo 'By default, runs against the configuration specified in `.env` file (see `example.env` for a template).'
+	@echo
+	@echo 'As specified above, the config file can be overridden using `PROD` or `TEST` commands, and a custom config file'
+	@echo 'can also be specified by explicitly setting the `ENV_FILE` variable, like: `make ENV_FILE=custom.env <command>`.'
+	@echo
+	@echo 'Note that different values of `TAG` specified in your config file will result in different container and asset'
+	@echo 'builds, which can be useful for (e.g.) testing out features while preserving mainline branch builds.'
 
 .DEFAULT_GOAL := help