From f0b7e6429731a71cc644547e24c148fe6276eff1 Mon Sep 17 00:00:00 2001
From: Hilary Holz <hholz@digitalocean.com>
Date: Thu, 18 Jul 2019 16:18:15 -0700
Subject: [PATCH] add descriptions to `make help`

---
 CONTRIBUTING.md |  4 ++--
 Makefile        | 23 ++++++++++++++++++-----
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ea67531b9..a7a9ae9bd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,8 +62,8 @@ lets us merge or address your contributions quickly.
 
 ## Developing
 
-`doctl` has `make` targets for most tooling in the `Makefile`. Run `make`
-or `make list` for a list of available targets.
+`doctl` has `make` commands for most tooling in the `Makefile`. Run `make`
+or `make help` for a list of available commands with descriptions.
 
 ### Go environment
 
diff --git a/Makefile b/Makefile
index cd7501470..3f053ccc4 100644
--- a/Makefile
+++ b/Makefile
@@ -1,34 +1,45 @@
-# need to set go version to at least 1.11
+# NOTE: Adding a target so it shows up in the help listing
+#    - The description is the text that is echoed in the first command in the target.
+#    - Only 'public' targets (start with an alphanumeric character) display in the help listing.
+#    - All public targets need a description
 
 export CGO = 0
 
 export GO111MODULE := on
 
-list:
+.PHONY: help
+help:
+	@echo "describe make commands"
+	@echo ""
 	@$(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null |\
-	  awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' |\
-	  sort |\
-	  egrep -v -e '^[^[:alnum:]]' -e '^$@$$'
+	  awk -v RS= -F: \
+	    '/^# File/,/^# Finished Make data base/ {if ($$1 ~ /^[a-zA-Z]/) {printf "%-15s%s\n", $$1, substr($$9, 9, length($$9)-9)}}' |\
+	  sort
 
 .PHONY: test
 test:
+	@echo "run tests"
 	go test ./cmd/... ./commands/... ./do/... ./install/... ./pkg/... ./pluginhost/... .
 
 .PHONY: clean
 clean:
+	@echo "remove build / release artifacts"
 	@rm -rf builds
 
 .PHONY: vendor
 vendor:
+	@echo "vendor dependencies"
 	go mod vendor
 	go mod tidy
 
 .PHONY: changelog
 changelog:
+	@echo "generate changelog entries"
 	scripts/changelog.sh
 
 .PHONY: mocks
 mocks:
+	@echo "update mocks"
 	scripts/regenmocks.sh
 
 # These builds are for convenience. This logic isn't used in the build-release process
@@ -58,6 +69,7 @@ _build:
 
 .PHONY: native
 native: _build
+	@echo "build local version"
 	@mv $(OUT_D)/doctl_$(GOOS)_$(GOARCH) $(OUT_D)/doctl
 	@echo "built $(OUT_D)/doctl"
 
@@ -70,6 +82,7 @@ _base_docker_cntr:
 
 .PHONY: docker_build
 docker_build: _base_docker_cntr
+	@echo "build doctl in local docker container"
 	@mkdir -p $(OUT_D)
 	@docker build -f Dockerfile.cntr . -t doctl_local
 	@docker run --rm \