feature: improve documentation (#15)

tkrop · Jan 7, 2024 · cf71d78 · cf71d78
1 parent 55809c6
commit cf71d78
Show file tree

Hide file tree

Showing 9 changed files with 104 additions and 58 deletions.
diff --git a/MANUAL.md b/MANUAL.md
@@ -1,16 +1,26 @@
 # `go-make` Manual
 
-[go-make][go-make] is a thin wrapper versioned wrapper around a very generic
-[Makefile](Makefile.base).
+[`go-make`][go-make] is a thin versioned wrapper around a very generic and
+customizable [`Makefile.base`](Makefile.base), that is usually wrapped by a
+short project [`Makefile`](Makefile). In this setup the commands `go-make`
+and `make` can be used as synonyms. In the following we use just `make`.
+Please substitute with `go-make`, if you have not installed the wrapper by
+initially calling `go-make init-make` on a project.
 
 [go-make]: https://github.com/tkrop/go-make
 
 
 ## Setup and customization
 
-The [Makefile](Makefile.base) is using sensitive defaults that are supposed to
-work out-of-the-box for most targets. Please see documentation of the target
-groups for more information on setup and customization:
+While [`make`][go-make] should work out-of-the-box by using sensitive defaults,
+the latest default [`Makefile`](Makefile) and [`Makefile.vars`](Makefile.vars)
+can be installed in a project directory through calling `make init-make`.
+Similar default config files for tools can be installed using `make init/<file>`
+to allow customization. All files can be updated by calling `make update-make`
+or simpler `make update`.
+
+For more information on customization, please see documentation of the different
+target groups:
 
 * [Standard targets](#standard-targets)
 * [Test targets](#test-targets)
@@ -27,11 +37,12 @@ groups for more information on setup and customization:
 
 **Note:** To see an overview of actual targets, use the shell auto-completion
 or run `make targets`. To get a short help on most important targets and target
-families run `make help`.
+families run `make help`. To have a look at the effective targets and receipts
+use `make show`.
 
-To customize the behavior of the Makefile there exist multiple extension points
-that can be used to setup additional variables, definitions, and targets that
-modify the behavior of the [Makefile](Makefile.base).
+To customize the behavior there exist multiple extension points that can be
+used to setup additional variables, definitions, and targets that modify the
+behavior of the targets and receipts.
 
 * [Makefile.vars](Makefile.vars) allows to modify the behavior of standard
   targets by customizing and defining additional variables (see section
@@ -42,15 +53,20 @@ modify the behavior of the [Makefile](Makefile.base).
 * [Makefile.ext](Makefile.ext) is an optional extension point that allows to
   define arbitrary custom targets.
 
-**Note:** To efficiently support custom targets the [Makefile](Makefile.base)
-is extensively making use of [Double Colon Rules][make-dcr] (`::`) for the main
-[phony targets][make-phony]. This makes it easy to define additional rules
-setting up new [prerequisite][make-prerequisite] and [receipts][make-receipts].
+**Note:** To efficiently support custom [targets][make-rules] and customization
+of [rules][make-rules] the [Makefile](Makefile.base) is extensively making use
+of [Double Colon Rules][make-double-colon] (`::`) for the main. This makes it
+easy to define additional rules setting up new [prerequisite][make-prerequisite]
+and [receipts][make-receipts] for [phony targets][make-phony]. Please read the
+great [GNU `make` manual][make] for more information on how [`make`][make] works
+and interacts with its execution environment.
 
-[make-dcr]: https://www.gnu.org/software/make/manual/html_node/Double_002dColon.html
+[make-rules]: https://www.gnu.org/software/make/manual/html_node/Rule-Introduction.html
+[make-double-colon]: https://www.gnu.org/software/make/manual/html_node/Double_002dColon.html
 [make-phony]: https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
 [make-prerequisite]: https://www.gnu.org/software/make/manual/html_node/Prerequisite-Types.html
 [make-receipts]: https://www.gnu.org/software/make/manual/html_node/Recipes.html
+[make]: https://www.gnu.org/software/make/manual/html_node/index.html
 
 
 ### Modifying variables

diff --git a/Makefile b/Makefile
@@ -8,12 +8,12 @@ else
 endif
 
 GOBIN ?= $(shell go env GOPATH)/bin
-GOMAKE ?= github.com/tkrop/[email protected].21
+GOMAKE ?= github.com/tkrop/[email protected].22
 TARGETS := $(shell command -v go-make >/dev/null || \
 	go install $(GOMAKE) && go-make targets)
 
 # Declare all targets phony to make them available for auto-completion.
-.PHONY: $(TARGETS)
+.PHONY:: $(TARGETS)
 
 # Delegate all targets to go-make in a single call suppressing other targets.
 $(eval $(wordlist 1,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))::;@:)

diff --git a/Makefile.base b/Makefile.base
@@ -239,6 +239,7 @@ MOCKS := $(shell for TARGET in $(MOCK_TARGETS); \
 TARGETS_PUBLISH := $(addprefix publish-, all $(COMMANDS))
 TARGETS_TEST_INIT := test-clean init-sources init-hooks
 TARGETS_INIT_MAKE := $(addprefix init/,$(INIT_MAKE))
+TARGETS_INIT_ALL := $(addprefix init/,$(sort $(INIT_MAKE) $(UPDATE_MAKE)))
 TARGETS_INIT_CODACY := $(addprefix init-, $(CODACY_BINARIES))
 TARGETS_LINT_CODACY_CLIENTS := $(addprefix lint-, $(CODACY_CLIENTS))
 TARGETS_LINT_CODACY_BINARIES := $(addprefix lint-, $(CODACY_BINARIES))
@@ -367,8 +368,8 @@ targets::
 	  else cat -; fi || true;
 
 #@ create a clone of the base repository to update from.
-BASE := [email protected]:tkrop/go-make.git
-setup/base::
+BASE ?= [email protected]:tkrop/go-make.git
+setup/base:: # TODO: support cloning of a distinct revision.
 	@$(eval BASEDIR = $(shell mktemp -d)) ( \
 	  trap "rm -rf $${DIR}" INT TERM EXIT; \
 	  while pgrep $(MAKE) > /dev/null; do sleep 1; done; \
@@ -387,7 +388,7 @@ git-message = \
 	    sed -E 's/^.*\(?([^() ]*\#[0-9]+)\)?.*$$/\1/')"; \
 	  NUMBER="$${COMMIT\#\#*\#}"; CONTEXT="$${COMMIT%%\#*}"; \
 	  MESSAGE="$${MESSAGE} ($${CONTEXT}\#$$((NUMBER+1)))"; \
-	fi; \
+	fi \
 
 #@ shows the git log as pretty printed graph.
 git-graph::
@@ -406,9 +407,9 @@ git-create-fix git-create-chore git-create-feature:: git-create-%:
 	@BRANCH="$(firstword $(RUNARGS))"; \
 	MESSAGE="$(wordlist 2,$(words $(RUNARGS)),$(RUNARGS))"; \
 	if [ -z "$${BRANCH}" ]; then BRANCH="update-deps"; fi; \
-	git checkout -B "$${BRANCH}"; $(call git-message,$*) \
-	git commit --message "$${MESSAGE}"; \
-	git push --set-upstream origin "$${BRANCH}";
+	$(call git-message,$*); \
+	git checkout -B "$${BRANCH}" && git commit --message "$${MESSAGE}" && \
+	git push --set-upstream origin "$${BRANCH}" || git checkout $${BRANCH};
 #@ <message> # commits the current change set using the given message using current issue.
 git-commit:: git-commit-feature
 git-commit-fix git-commit-chore git-commit-feature:: git-commit-%:
@@ -469,7 +470,7 @@ $(TARGETS_INIT_CODACY):: init-%:
 
 #@ initialize project by copying config files from template.
 init-make:: $(TARGETS_INIT_MAKE) $(TARGETS_UPDATE_MAKE)
-$(TARGETS_INIT_MAKE):: init/%: setup/base
+$(TARGETS_INIT_ALL):: init/%: setup/base
 	@DIR="$$(pwd)"; FILE="$*"; FILE="$${FILE##$(DIR_CONFIG)}"; \
 	cd "$(BASEDIR)"; git show HEAD:config/$${FILE} > $${DIR}/$${FILE} 2>/dev/null; \
 
@@ -1225,10 +1226,6 @@ $(TARGETS_CLEAN_RUN):: clean-run-%: run-clean-%
 
 ## Update: targets to update tools, configs, and dependencies.
 
-# TODO:
-# 'update-deps' check how to utilize: 'go list -m -u -mod=mod all'
-
-
 #@ update default or customized update targets.
 update:: $(TARGETS_UPDATE)
 #@ check default or customized update targets for updates.
@@ -1277,6 +1274,8 @@ update-list = \
 	  go list -m -u -mod=mod $(2) | grep "\[.*\]$$" \
 	) | sort -u | sed "s/\]//g; s/\[/=> /"
 
+# TODO: check how to utilize: 'go list -m -u -mod=mod all' in 'update-deps'.
+
 #@ [major|pre|minor] # update minor (and major) dependencies to latest versions.
 update-deps:: test-go update/go.mod
 update/go.mod:: $(GOBIN)/gomajor

diff --git a/README.md b/README.md
@@ -47,8 +47,8 @@
 
 ## Introduction
 
-Goal of `go-make` is to provide a simple, versioned build environment for
-standard [`go`][go]-projects (see [Standard `go`-project](#standard-go-project)
+Goal of `go-make` is to provide a simple, versioned test and build environment
+for usual [`go`][go]-projects (see [Standard `go`-project](#standard-go-project)
 for details) providing default targets, tools, and configs for testing, linting,
 building, installing, updating, running, and releasing libraries, commands, and
 container images.
@@ -67,13 +67,18 @@ is based on a standard [`go`][go]-project supporting different tools:
 * [`syft`][syft] - for material listing.
 
 The thin wrapper provides the necessary version control for the `Makefile` and
-the default config of integrated tools. It installs these tools automatically
-when needed in the latest available version.
+the default [`config`](config) of integrated tools. The tools are automatically
+installed when needed in the latest available version and use the default
+config. All config files can be installed and customized (see [Setup and
+customization](MANUAL.md#setup-and-customization)).
 
-**Note:** We accept the risk that using the latest versions of tools, e.g. for
-linting, may break the build for the sake of constantly updating dependencies by
-default. For tools where this is not desireable, the default import is/can be
-changed to contain a version (see [manual](MANUAL.md] for more information).
+
+**Note:** Mostly, we accept the risk that using the latest versions of tools,
+e.g. for linting, may break the build for the sake of constantly updating
+dependencies by default. For tools where this is not desireable, e.g. `revive`
+and `golangci-lint` the default import is setup to contain a version. This can
+be adopted for other tools if needed (see [manual](MANUAL.md) for more
+information).
 
 **Warning:** `go-make` automatically installs a `pre-commit` hook overwriting
 and deleting any pre-existing hook. The hook calls `go-make commit` to enforce
@@ -126,9 +131,9 @@ by the runtime environment, e.g. using [`ubuntu-20.04`][ubuntu-20.04] or
 
 ## Example usage
 
-After installing `go-make` and in the build environment, you can run all targets
-by simply calling `go-make <target>` on the command line, in another `Makefile`,
-in a github action, or any other delivery pipeline config script:
+After installing `go-make`, all provided targets can executed by simply calling
+`go-make <target>` in the project repository on the command line, in another
+`Makefile`, in a github action, or any other delivery pipeline config script:
 
 ```bash
 go-make all        # execute a whole build pipeline depending on the project.
@@ -138,6 +143,10 @@ go-make image      # execute minimal steps to create all container images.
 
 For further examples see [`go-make` manual](MANUAL.md).
 
+**Note:** Many `go-make` targets can be customized via environment variables,
+that by default are defined via [`Makefile.vars`](Makefiles.vars) (see also
+[Modifying variables](Manual.md#modifying-variables)).
+
 
 ## Makefile integration
 
@@ -153,14 +162,18 @@ TARGETS := $(shell command -v go-make >/dev/null || \
    go install $(GOMAKE) && go-make targets)
 
 # Declare all targets phony to make them available for auto-completion.
-.PHONY: $(TARGETS)
+.PHONY:: $(TARGETS)
 
 # Delegate all targets to go-make in a single call suppressing other targets.
 $(eval $(wordlist 1,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))::;@:)
 $(firstword $(MAKECMDGOALS) all)::
    $(GOBIN)/go-make $(MAKEFLAGS) $(MAKECMDGOALS);
 ```
 
+The default [`Makefile`](Makefile) can also be installed to a project from the
+template via `go-make init-make`. Other default [config](config) files can be
+installed using `go-make init/<file>`.
+
 
 ## Shell integration
 
@@ -172,6 +185,16 @@ source <(go-make --completion=bash)
 ```
 
 
+## Makefile development
+
+To extend the `Makefile`, you develop own receipts in a custom file called
+[`Makefile.ext`](Makefile.ext) that is included automatically. If you want to
+extend original receipts, you can replace the wrapper [`Makefile`](Makefile)
+and install [`Makefile.base`](Makefile.base) and the [`MANUAL.md`](MANUAL.md)
+in your project by calling `go-make init-make!`. But be careful, this command
+always overwrites your `Makefile` with the latest version.
+
+
 ## Standard `go`-Project
 
 The [Makefile](Makefile) provided in this project is working under the
@@ -224,9 +247,8 @@ targets as necessary.
 ## Terms of usage
 
 This software is open source as is under the MIT license. If you start using
-the software, please give it a star, so that I know to be more careful with
-changes. If this project has more than 25 Stars, I will introduce semantic
-versions for changes.
+the software, please give it a star, so that I know to be more careful to keep
+changes non-breaking.
 
 
 ## Building
@@ -244,4 +266,4 @@ make -f Makefile.base <target>...
 
 If you like to contribute, please create an issue and/or pull request with a
 proper description of your proposal or contribution. I will review it and
-provide feedback on it.
+provide feedback on it as soon as possible.
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.0.21
+0.0.22
diff --git a/config/Makefile b/config/Makefile
@@ -8,12 +8,12 @@ else
 endif
 
 GOBIN ?= $(shell go env GOPATH)/bin
-GOMAKE ?= github.com/tkrop/[email protected].21
+GOMAKE ?= github.com/tkrop/[email protected].22
 TARGETS := $(shell command -v go-make >/dev/null || \
 	go install $(GOMAKE) && go-make targets)
 
 # Declare all targets phony to make them available for auto-completion.
-.PHONY: $(TARGETS)
+.PHONY:: $(TARGETS)
 
 # Delegate all targets to go-make in a single call suppressing other targets.
 $(eval $(wordlist 1,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))::;@:)

diff --git a/config/Makefile.base b/config/Makefile.base
@@ -239,6 +239,7 @@ MOCKS := $(shell for TARGET in $(MOCK_TARGETS); \
 TARGETS_PUBLISH := $(addprefix publish-, all $(COMMANDS))
 TARGETS_TEST_INIT := test-clean init-sources init-hooks
 TARGETS_INIT_MAKE := $(addprefix init/,$(INIT_MAKE))
+TARGETS_INIT_ALL := $(addprefix init/,$(sort $(INIT_MAKE) $(UPDATE_MAKE)))
 TARGETS_INIT_CODACY := $(addprefix init-, $(CODACY_BINARIES))
 TARGETS_LINT_CODACY_CLIENTS := $(addprefix lint-, $(CODACY_CLIENTS))
 TARGETS_LINT_CODACY_BINARIES := $(addprefix lint-, $(CODACY_BINARIES))
@@ -367,8 +368,8 @@ targets::
 	  else cat -; fi || true;
 
 #@ create a clone of the base repository to update from.
-BASE := [email protected]:tkrop/go-make.git
-setup/base::
+BASE ?= [email protected]:tkrop/go-make.git
+setup/base:: # TODO: support cloning of a distinct revision.
 	@$(eval BASEDIR = $(shell mktemp -d)) ( \
 	  trap "rm -rf $${DIR}" INT TERM EXIT; \
 	  while pgrep $(MAKE) > /dev/null; do sleep 1; done; \
@@ -387,7 +388,7 @@ git-message = \
 	    sed -E 's/^.*\(?([^() ]*\#[0-9]+)\)?.*$$/\1/')"; \
 	  NUMBER="$${COMMIT\#\#*\#}"; CONTEXT="$${COMMIT%%\#*}"; \
 	  MESSAGE="$${MESSAGE} ($${CONTEXT}\#$$((NUMBER+1)))"; \
-	fi; \
+	fi \
 
 #@ shows the git log as pretty printed graph.
 git-graph::
@@ -406,9 +407,9 @@ git-create-fix git-create-chore git-create-feature:: git-create-%:
 	@BRANCH="$(firstword $(RUNARGS))"; \
 	MESSAGE="$(wordlist 2,$(words $(RUNARGS)),$(RUNARGS))"; \
 	if [ -z "$${BRANCH}" ]; then BRANCH="update-deps"; fi; \
-	git checkout -B "$${BRANCH}"; $(call git-message,$*) \
-	git commit --message "$${MESSAGE}"; \
-	git push --set-upstream origin "$${BRANCH}";
+	$(call git-message,$*); \
+	git checkout -B "$${BRANCH}" && git commit --message "$${MESSAGE}" && \
+	git push --set-upstream origin "$${BRANCH}" || git checkout $${BRANCH};
 #@ <message> # commits the current change set using the given message using current issue.
 git-commit:: git-commit-feature
 git-commit-fix git-commit-chore git-commit-feature:: git-commit-%:
@@ -469,7 +470,7 @@ $(TARGETS_INIT_CODACY):: init-%:
 
 #@ initialize project by copying config files from template.
 init-make:: $(TARGETS_INIT_MAKE) $(TARGETS_UPDATE_MAKE)
-$(TARGETS_INIT_MAKE):: init/%: setup/base
+$(TARGETS_INIT_ALL):: init/%: setup/base
 	@DIR="$$(pwd)"; FILE="$*"; FILE="$${FILE##$(DIR_CONFIG)}"; \
 	cd "$(BASEDIR)"; git show HEAD:config/$${FILE} > $${DIR}/$${FILE} 2>/dev/null; \
 
@@ -1225,10 +1226,6 @@ $(TARGETS_CLEAN_RUN):: clean-run-%: run-clean-%
 
 ## Update: targets to update tools, configs, and dependencies.
 
-# TODO:
-# 'update-deps' check how to utilize: 'go list -m -u -mod=mod all'
-
-
 #@ update default or customized update targets.
 update:: $(TARGETS_UPDATE)
 #@ check default or customized update targets for updates.
@@ -1277,6 +1274,8 @@ update-list = \
 	  go list -m -u -mod=mod $(2) | grep "\[.*\]$$" \
 	) | sort -u | sed "s/\]//g; s/\[/=> /"
 
+# TODO: check how to utilize: 'go list -m -u -mod=mod all' in 'update-deps'.
+
 #@ [major|pre|minor] # update minor (and major) dependencies to latest versions.
 update-deps:: test-go update/go.mod
 update/go.mod:: $(GOBIN)/gomajor

diff --git a/internal/make/fixtures/targets-trace.out b/internal/make/fixtures/targets-trace.out
@@ -1,4 +1,4 @@
-Makefile.base:361: target 'targets' does not exist
+Makefile.base:362: target 'targets' does not exist
 make --no-builtin-rules --no-builtin-variables --print-data-base \
   --question --makefile=Makefile.base 2>/dev/null | \
   if [ "" != "raw" ]; then awk -v RS= -F: ' \
@@ -51,8 +51,13 @@ init-make
 init-make!
 init-sources
 init-staticcheck
+init/.codacy.yaml
+init/.gitleaks.toml
+init/.golangci.yaml
+init/.markdownlint.yaml
 init/Makefile
 init/Makefile.vars
+init/revive.toml
 install
 install-all
 install-deadcode

diff --git a/internal/make/fixtures/targets.out b/internal/make/fixtures/targets.out
@@ -43,8 +43,13 @@ init-make
 init-make!
 init-sources
 init-staticcheck
+init/.codacy.yaml
+init/.gitleaks.toml
+init/.golangci.yaml
+init/.markdownlint.yaml
 init/Makefile
 init/Makefile.vars
+init/revive.toml
 install
 install-all
 install-deadcode