Skip to content
Documentation
Reference
Makefile and Repository Layout

Makefile and Repository Layout

make help

Captured by running make help from the repository root:

$ make help
  help         Show this help
  test         Run unit tests with the race detector
  lint         Run gofmt check, go vet, and golangci-lint
  vuln         Run govulncheck
  build        Build bin/jev
  release      Tag and push a release: make release VERSION=vX.Y.Z (runs lint and test first)
  integration  Run the live API test (needs TYPESAFE_API_KEY)
  review       Run jev review against this repository (needs TYPESAFE_API_KEY)
  docs         Build the site and check that every docs/ page is reachable and links resolve
  site         Build the documentation site into site/public
  site-serve   Serve the documentation site locally with live reload
  clean        Remove build outputs

make release

make release VERSION=vX.Y.Z validates the repository state, then tags and pushes a release. It performs these checks and actions, in order:

  1. VERSION must match ^v[0-9]+\.[0-9]+\.[0-9]+$ (for example v1.2.3).
  2. The working tree must have no uncommitted changes.
  3. The current branch must be main.
  4. It fetches origin main, then requires local HEAD to match origin/main exactly.
  5. The tag must not already exist locally.
  6. The tag must not already exist on the origin remote.
  7. It runs make lint test, which must pass.
  8. It creates an annotated tag: git tag -a "VERSION" -m "typesafe-go VERSION".
  9. It pushes the tag: git push origin "VERSION".
  10. It prints a confirmation line.

Pushing the tag triggers the release.yml GitHub Actions workflow, described under release.yml below.

For the full release procedure and what GoReleaser produces from the tag, see Cut a release.

Repository layout

One line per top-level directory and top-level package, as they exist in the repository root at the time this page was written:

PathContents
*.go (repository root)The typesafe client library package (module github.com/therealbill/typesafe-go): client.go, errors.go, instrument.go, models.go, question.go, response.go, retry.go, transport.go, typed.go, doc.go, plus each file’s _test.go counterpart and integration_test.go.
cmd/jevThe jev binary’s main package (main.go); calls internal/cli.Main.
internal/cliThe jev command implementation: root.go, ask.go, models.go, version.go, request.go, exit.go, output.go, telemetry.go, review.go, and their _test.go counterparts.
internal/reviewThe review logic behind jev review: review.go, template.go, review_test.go. Documented on the jev review reference.
otelThe typesafe/otel package: an Instrumentation implementation (otel.go) that reports OpenTelemetry traces for client calls, plus otel_test.go.
toolscheckdocs.sh, the documentation link checker make docs runs.
jev-review.json (repository root)This repository’s own jev review config.
testdataFixture JSON files: models_ok.json, request.json, systemone_ok.json.
docsThis documentation set: _index.md plus explanation, how-to, reference, superpowers, and tutorials subdirectories.
siteThe Hugo site that builds docs/ (present in the repository at the time of writing): hugo.toml, go.mod, go.sum, content, layouts, resources, public.
.github/workflowsCI/CD workflow definitions: ci.yml, hugo-deploy.yml, hugo-pr.yml, release.yml.

GitHub Actions workflows

Read from .github/workflows/ at the time of writing.

ci.yml (name: ci)

Triggers on push to branch main, and on every pull_request. Two jobs:

JobSteps
testChecks out the repository, sets up Go from go.mod, runs go test -race -cover ./..., then go run golang.org/x/vuln/cmd/govulncheck@latest ./....
lintChecks out the repository, sets up Go from go.mod, runs golangci/golangci-lint-action@v8 at version: v2.5.

hugo-deploy.yml (name: Deploy documentation site)

Triggers on push to branch main when the change touches docs/**, site/**, or .github/workflows/hugo-deploy.yml, and on workflow_dispatch. Permissions: contents: read, pages: write, id-token: write. Concurrency group pages with cancel-in-progress: false. Two jobs:

JobSteps
buildInstalls Hugo 0.166.0 (extended, via a downloaded .deb), checks out with fetch-depth: 0, sets up Go from go.mod, configures GitHub Pages (actions/configure-pages@v5), caches ~/.cache/hugo_cache keyed on site/go.sum, runs hugo --gc --minify -s site --baseURL "<pages base url>/", and uploads site/public as the Pages artifact.
deploy (needs build)Runs actions/deploy-pages@v4 against the github-pages environment.

hugo-pr.yml (name: Documentation site build check)

Triggers on pull_request when the change touches docs/**, site/**, or .github/workflows/hugo-pr.yml. One job:

JobSteps
buildInstalls Hugo 0.166.0 (extended, via a downloaded .deb), checks out with fetch-depth: 0, sets up Go from go.mod, runs hugo --gc --minify -s site --baseURL "https://therealbill.github.io/typesafe-go/", then appends a page count (find site/public -name index.html | wc -l) and a size (du -sh site/public) to $GITHUB_STEP_SUMMARY.

release.yml (name: release)

Triggers on push of a tag matching v*. Permissions: contents: write. One job:

JobSteps
goreleaserChecks out with fetch-depth: 0, sets up Go from go.mod, runs goreleaser/goreleaser-action@v6 (distribution goreleaser, version ~> v2) with args: release --clean, using GITHUB_TOKEN from secrets.GITHUB_TOKEN.
jev review