✨ housekeeping: Improve docs and make help (#228)

- Document release process.
- Make first README.md link point to evy.dev rather than scratch.
- Replace sponsorship red heart emoji with a white one for readability.

Update `make help` awk scripts for multi-line comments on top or rather than
next to target.

Add `/version` endpoint to deployment.

This merges the following commits:
* tools: Update `make help` scripting
* docs: Replace sponsorship heart emoji
* docs: Make first README.md link point to evy.dev
* docs: Add releasing documentation
* frontend: Add version endpoint

     Makefile                      | 74 +++++++++++++++++++++++++----------
     README.md                     |  5 ++-
     docs/development/releasing.md | 30 ++++++++++++++
     firebase/firebase.json        |  6 +++
     4 files changed, 92 insertions(+), 23 deletions(-)

Pull-Request: #228

Makefile

@@ -28,23 +28,27 @@ CMDS = .
 build: | $(O) ## Build evy binaries
 	go build -o $(O) -ldflags='$(GO_LDFLAGS)' $(CMDS)
 
-install: ## Build and install binaries in $GOBIN
+## Build and install binaries in $GOBIN
+install:
 	go install -ldflags='$(GO_LDFLAGS)' $(CMDS)
 
 # Use `go version` to ensure the right go version is installed when using tinygo.
 go-version:
 	go version
 
-# Optimise tinygo output for size, see https://www.fermyon.com/blog/optimizing-tinygo-wasm
-tiny: go-version | $(O) ## Build for tinygo / wasm
+## Build with tinygo targeting wasm
+# optimise for size, see https://www.fermyon.com/blog/optimizing-tinygo-wasm
+tiny: go-version | $(O)
 	GOOS=wasip1 GOARCH=wasm tinygo build -o $(O)/evy-unopt.wasm -no-debug -ldflags='$(GO_LDFLAGS)' -stack-size=512kb ./pkg/wasm
 	wasm-opt -O3 $(O)/evy-unopt.wasm -o frontend/evy.wasm
 	cp -f $$(tinygo env TINYGOROOT)/targets/wasm_exec.js frontend/
 
-tidy: ## Tidy go modules with "go mod tidy"
+## Tidy go modules with "go mod tidy"
+tidy:
 	go mod tidy
 
-fmt: ## Format all go files with gofumpt, a stricter gofmt
+## Format all go files with gofumpt, a stricter gofmt
+fmt:
 	gofumpt -w $(GOFILES)
 
 clean::
@@ -56,16 +60,20 @@ clean::
 # --- Test ---------------------------------------------------------------------
 COVERFILE = $(O)/coverage.txt
 
-test: | $(O) ## Run non-tinygo tests and generate a coverage file
+## Run non-tinygo tests and generate a coverage file
+test: | $(O)
 	go test -coverprofile=$(COVERFILE) ./...
 
-test-tiny: go-version | $(O) ## Run tinygo tests
+## Run tinygo tests
+test-tiny: go-version | $(O)
 	tinygo test ./...
 
-check-coverage: test ## Check that test coverage meets the required level
+## Check that test coverage meets the required level
+check-coverage: test
 	@go tool cover -func=$(COVERFILE) | $(CHECK_COVERAGE) || $(FAIL_COVERAGE)
 
-cover: test ## Show test coverage in your browser
+## Show test coverage in your browser
+cover: test
 	go tool cover -html=$(COVERFILE)
 
 CHECK_COVERAGE = awk -F '[ \t%]+' '/^total:/ {print; if ($$3 < $(COVERAGE)) exit 1}'
@@ -75,10 +83,13 @@ FAIL_COVERAGE = { echo '$(COLOUR_RED)FAIL - Coverage below $(COVERAGE)%$(COLOUR_
 
 # --- Lint ---------------------------------------------------------------------
 EVY_FILES = $(shell find frontend/samples -name '*.evy')
-lint: ## Lint go source code
+
+## Lint go source code
+lint:
 	golangci-lint run
 
-evy-fmt: ## Format evy sample code
+## Format evy sample code
+evy-fmt:
 	go run . fmt --write $(EVY_FILES)
 
 check-evy-fmt:
@@ -114,17 +125,22 @@ godoc: install
 # --- frontend -----------------------------------------------------------------
 NODELIB = .hermit/node/lib
 
-frontend: tiny | $(O) ## Build frontend, typically iterate with npm and inside frontend
+## Build frontend, typically iterate with npm and inside frontend
+frontend: tiny | $(O)
 	rm -rf $(O)/public
 	cp -r frontend $(O)/public
+	echo '{ "version": "$(VERSION)" }' | jq > $(O)/public/version.json
 
-frontend-serve: frontend ## Build frontend and serve on free port
+## Build frontend and serve on free port
+frontend-serve: frontend
 	servedir $(O)/public
 
-prettier: | $(NODELIB) ## Format code with prettier
+## Format code with prettier
+prettier: | $(NODELIB)
 	npx -y prettier --write .
 
-check-prettier: | $(NODELIB)  ## Ensure code is formatted with prettier
+## Ensure code is formatted with prettier
+check-prettier: | $(NODELIB)
 	npx -y prettier --check .
 
 $(NODELIB):
@@ -134,13 +150,16 @@ $(NODELIB):
 
 # --- firebase -----------------------------------------------------------------
 
-firebase-deploy-prod: firebase-public ## Deploy to live channel on firebase, use with care!
+## Deploy to live channel on firebase, use with care!
+firebase-deploy-prod: firebase-public
 	./scripts/firebase-deploy live
 
-firebase-deploy: firebase-public ## Deploy to dev (or other) channel on firebase
+## Deploy to dev (or other) channel on firebase
+firebase-deploy: firebase-public
 	./scripts/firebase-deploy
 
-firebase-emulate: firebase-public ## Run firebase emulator for auth, hosting and datastore
+## Run firebase emulator for auth, hosting and datastore
+firebase-emulate: firebase-public
 	firebase --config firebase/firebase.json emulators:start
 
 firebase-public: frontend
@@ -152,11 +171,13 @@ firebase-public: frontend
 # --- scripts ------------------------------------------------------------------
 SCRIPTS = scripts/firebase-deploy .github/scripts/app_token
 
-sh-lint: ## Lint script files with shellcheck and shfmt
+## Lint script files with shellcheck and shfmt
+sh-lint:
 	shellcheck $(SCRIPTS)
 	shfmt --diff $(SCRIPTS)
 
-sh-fmt:  ## Format script files
+## Format script files
+sh-fmt:
 	shfmt --write $(SCRIPTS)
 
 .PHONY: sh-fmt sh-lint
@@ -191,13 +212,24 @@ COLOUR_GREEN  = $(shell tput setaf 2 2>/dev/null)
 COLOUR_WHITE  = $(shell tput setaf 7 2>/dev/null)
 
 help:
-	@awk -F ':.*## ' 'NF == 2 && $$1 ~ /^[A-Za-z0-9%_-]+$$/ { printf "$(COLOUR_WHITE)%-25s$(COLOUR_NORMAL)%s\n", $$1, $$2}' $(MAKEFILE_LIST) | sort
+	$(eval export HELP_AWK)
+	@awk "$${HELP_AWK}" $(MAKEFILE_LIST) | sort | column -s "$$(printf \\t)" -t
 
 $(O):
 	@mkdir -p $@
 
 .PHONY: help
 
+# Awk script to extract and print target descriptions for `make help`.
+define HELP_AWK
+/^## / { desc = desc substr($$0, 3) }
+/^[A-Za-z0-9%_-]+:/ && desc {
+	sub(/:$$/, "", $$1)
+	printf "$(COLOUR_WHITE)%s$(COLOUR_NORMAL)\t%s\n", $$1, desc
+	desc = ""
+}
+endef
+
 define nl
 
 

README.md

@@ -3,9 +3,9 @@
 [![Discord Chat](https://img.shields.io/badge/discord-chat-414eed?style=flat-square&logo=discord&logoColor=white)](https://evy.dev/discord)
 [![GitHub Build](https://img.shields.io/github/actions/workflow/status/evylang/evy/cicd.yaml?style=flat-square&branch=main&logo=github)](https://github.com/evylang/evy/actions/workflows/cicd.yaml?query=branch%3Amain)
 [![Go Reference](https://pkg.go.dev/badge/evylang.dev/evy.svg)](https://pkg.go.dev/evylang.dev/evy)
-[![GitHub Sponsorship](https://img.shields.io/badge/sponsor-%E2%9D%A4-eb5c95?style=flat-square&logo=github&logoColor=white)](https://github.com/sponsors/evylang)
+[![GitHub Sponsorship](https://img.shields.io/badge/sponsor-%E2%99%A5-eb5c95?style=flat-square&logo=github&logoColor=white)](https://github.com/sponsors/evylang)
 
-Evy is a simple programming language, made to learn coding.
+Evy is a simple programming language, made to learn coding. [Try it out].
 
 Evy bridges the gap between block-based languages like [Scratch] and
 conventional languages like Python or JavaScript. It has a minimalist
@@ -15,6 +15,7 @@ programming languages. Evy has a small set of
 remember, but it still is powerful enough for user interaction, games,
 and animations.
 
+[Try it out]: https://evy.dev/play
 [Scratch]: https://scratch.mit.edu/
 
 ## 🌱 Getting Started

docs/development/releasing.md

@@ -0,0 +1,30 @@
+# Releasing
+
+Evy automatically releases with every new merge to the `main` branch on GitHub.
+This process publishes artifacts for all major operating systems and
+architectures under [releases] as part of a successful CI run. Additionally,
+the `evylang/tap/evy` brew formula is updated to the latest version.
+
+By default, each release receives a semantic **patch** bump. For example, if the
+latest version is `v0.2.4`, the next one will be `v0.2.5` by default.
+
+To trigger a minor version bump, add a new file to the
+[release-notes directory]. A minor version bump indicates the completion of a
+[milestone]. The release notes file should be named according to the new
+version, for example, `v0.2.0.md`.
+
+To trigger a **minor** version bump a new file must be added to the
+[release-notes directory]. A minor version bump signifies the completion of a
+milestone. The release notes file is named according to the new version, for
+example `v0.2.0.md`.
+
+Evy's current major version is still 0, this may change in the future.
+Evy's language syntax, tooling, and public API are still under development
+and not yet considered stable. Additionally, for major version 0, the meaning
+of patch and minor versions does not conform to the standard
+[semantic versioning specifications].
+
+[releases]: https://github.com/evylang/evy/releases
+[milestone]: https://github.com/evylang/evy/milestones
+[release-notes directory]: https://github.com/evylang/evy/tree/main/docs/release-notes
+[semantic versioning specifications]: https://semver.org/

firebase/firebase.json

@@ -27,6 +27,12 @@
         "destination": "/",
         "type": 301
       }
+    ],
+    "rewrites": [
+      {
+        "source": "/version",
+        "destination": "/version.json"
+      }
     ]
   },
   "emulators": {