ci: add usual release procedures to this project (#41)

## Which problem is this PR solving?

- Anemic releasing docs. Let's bring it in-line with how we're releasing
other Go libraries.

## Short description of the changes

- added our usual release automation CI job (and put its smarts into a
Makefile)
- added a test target to the Makefile to match other Go libraries, and
config CI to record test results
- added RELEASING so the next human that needs to pull the release lever
has some guidance

.circleci/config.yml

@@ -3,6 +3,20 @@ version: 2.1
 orbs:
   buildevents: honeycombio/buildevents@0.9.0
 
+# enable a job when tag created (tag create is ignored by default)
+filters_always: &filters_always
+  filters:
+    tags:
+      only: /.*/
+
+# restrict a job to only run when a version tag (vNNNN) is created
+filters_publish: &filters_publish
+  filters:
+    tags:
+      only: /^v[0-9].*/
+    branches:
+      ignore: /.*/
+
 matrix_goversions: &matrix_goversions
   matrix:
     parameters:
@@ -21,6 +35,9 @@ executors:
       - image: cimg/go:1.<< parameters.goversion >>
         environment:
           GO111MODULE: "on"
+  github:
+    docker:
+      - image: cibuilds/github:0.13.0
 
 jobs:
   setup:
@@ -44,20 +61,36 @@ jobs:
       - buildevents/with_job_span:
           steps:
             - checkout
-            - run: go get -v -t -d ./...
-            - run: go test -race -v ./...
+            - run: make test
+            - store_test_results:
+                path: ./unit-tests.xml
             - buildevents/add_context:
                 field_name: go_version
                 field_value: << parameters.goversion >>
 
+  publish_github:
+    executor: github
+    steps:
+      - attach_workspace:
+          at: ~/
+      - run:
+          name: "create draft release at GitHub"
+          command: make publish_github
+
 workflows:
-  test:
+  build:
     jobs:
       - setup
       - watch:
           requires:
             - setup
       - test:
           <<: *matrix_goversions
+          <<: *filters_always
+          requires:
+            - setup
+      - publish_github:
+          <<: *filters_publish
+          context: Honeycomb Secrets for Public Repos
           requires:
             - setup

Makefile

@@ -0,0 +1,55 @@
+.PHONY: test
+#: run the tests!
+test:
+ifeq (, $(shell which gotestsum))
+	@echo " ***"
+	@echo "Running with standard go test because gotestsum was not found on PATH. Consider installing gotestsum for friendlier test output!"
+	@echo " ***"
+	go test -race -v ./...
+else
+	gotestsum --junitfile unit-tests.xml --format testname -- -race ./...
+endif
+
+#########################
+###     RELEASES      ###
+#########################
+
+CIRCLE_TAG ?=
+RELEASE_VERSION ?= $(or $(CIRCLE_TAG), $(shell git describe --tags))
+
+.PHONY: publish_github
+#: draft a GitHub release for current commit/tag and upload builds as its assets
+publish_github: github_prereqs
+	@echo "+++ drafting GitHub release, tag $(RELEASE_VERSION)"
+	@ghr -draft \
+	     -name ${RELEASE_VERSION} \
+	     -token ${GITHUB_TOKEN} \
+	     -username ${CIRCLE_PROJECT_USERNAME} \
+	     -repository ${CIRCLE_PROJECT_REPONAME} \
+	     -commitish ${CIRCLE_SHA1} \
+	     ${RELEASE_VERSION}
+
+.PHONY: github_prereqs
+github_prereqs: ghr_present
+	@:$(call check_defined, RELEASE_VERSION, the tag from which to create this release)
+	@:$(call check_defined, GITHUB_TOKEN, auth to create this release)
+	@:$(call check_defined, CIRCLE_PROJECT_USERNAME, user who will create this release)
+	@:$(call check_defined, CIRCLE_PROJECT_REPONAME, the repository getting a new release)
+	@:$(call check_defined, CIRCLE_SHA1, the git ref to associate with this release)
+
+
+#################
+### Utilities ###
+#################
+
+.PHONY: ghr_present
+ghr_present:
+	@which ghr || (echo "ghr missing; required to create release at GitHub"; exit 1)
+
+check_defined = \
+    $(strip $(foreach 1,$1, \
+        $(call __check_defined,$1,$(strip $(value 2)))))
+__check_defined = \
+    $(if $(value $1),, \
+        $(error Undefined $1$(if $2, ($2))$(if $(value @), \
+                required by target `$@')))

RELEASING.md

@@ -0,0 +1,7 @@
+# Release Process
+
+1. Add release entry to [changelog](./CHANGELOG.md)
+2. Open a PR with above changes.
+3. Once the above PR is merged, pull the updated `main` branch down and tag the merged release commit on `main` with the new version, e.g. `git tag -a v2.3.1 -m "v2.3.1"`.
+4. Push the tag, e.g. `git push origin v2.3.1`. This will kick off a CI workflow, which will publish a draft GitHub release.
+5. Update Release Notes on the new draft GitHub release by generating notes with the button and review for any PR titles that could use some wordsmithing or recategorization.