watchtower/docs/developer-guide.md

Developer Guide — Running tests & race detector

This short guide covers how to run unit tests locally and how to run the race-enabled test suite in a Linux container (recommended for Windows hosts).

Prerequisites

• Go toolchain (version compatible with project go.mod). To run go test locally, ensure go is in your PATH.
• Docker (for running a Linux container to execute -race with CGO enabled)
• Optional: GitHub CLI gh to open PRs from the command line.

Run unit tests locally

From the repository root:

PowerShell

go test ./... -v

If you only want to run a package tests, run:

go test ./pkg/registry/auth -v

Run race detector (recommended via container on Windows)

The Go race detector requires cgo and a C toolchain. On Linux runners this is usually available; on Windows it's simplest to run tests inside a Linux container.

Example (PowerShell):

docker run --rm -v "${PWD}:/work" -w /work -e CGO_ENABLED=1 golang:1.20 bash -lc "apt-get update && apt-get install -y build-essential ; /usr/local/go/bin/go test -race ./... -v"

Notes:

• The command mounts the current working directory into the container and installs build-essential to provide a C toolchain so -race works.
• If you prefer a faster run, run go test -run TestName ./pkg/yourpkg -race.

Render PlantUML diagrams (local)

To render PlantUML into SVG using Docker (no Java/PlantUML install required):

docker run --rm -v "${PWD}:/work" -w /work plantuml/plantuml -tsvg docs/diagrams/update-flow.puml

Move the generated SVG into the docs assets folder:

mkdir docs/assets/images -Force
Move-Item docs/diagrams/update-flow.svg docs/assets/images/update-flow.svg -Force

Create a branch and PR (example)

Example git commands:

git checkout -b docs/update-flow
git add docs/update-flow.md docs/diagrams/update-flow.puml docs/developer-guide.md docs/assets/images/update-flow.svg
git commit -m "docs: add update flow docs, diagrams and developer guide"
git push -u origin docs/update-flow

If you have the GitHub CLI installed you can open a PR with:

gh pr create --title "docs: update flow + diagrams" --body "Adds update flow documentation, a PlantUML diagram and developer guide." --base main

If gh is not installed you can open a PR via GitHub web UI after pushing the branch.

---

If you'd like, I can push the branch and attempt to open the PR for you now.