Development
For: contributors. At the end: you can set up the project, run every check, and cut a release.
Everything needed to work on wow-stats and cut a release. The command and the
Python package are wow-stats; the images are wow-mcp and wow-mcp-render.
Set up
Section titled “Set up”Python goes through uv only.
uv sync --frozen --extra publish --extra mcp --group browseruv run playwright install chromium webkitThe browser group and the two browsers are for the browser tests
(tests/test_browser.py, tests/test_advice_browser.py). Without them those
tests skip; CI doesn’t install them, so run them locally before a release.
The checks
Section titled “The checks”uv run ruff check .uv run pytest -q -rs # about 950 tests, a few minutes; -rs lists what skippeddocker build -t wow-stats:dev .docker build --target renderer -t wow-stats-render:dev .What skips without what:
| Tests | Need |
|---|---|
| browser tests | the browser group and its browsers |
tests/test_compose.py |
docker compose |
tests/test_windows_e2e.py |
Windows (CI runs it on windows-latest) |
tests/test_renderer_browser.py, tests/test_model3d_browser.py |
WOW_STATS_BROWSER=1: they fetch Wowhead’s viewer over the network |
tests/test_gear_parity.py |
POLESTAR_CHECKOUT: a Polestar clone at the pinned tag (docs/gear-reference.md) |
tests/test_public_scan.py, the name check |
the denylist file (below) |
Optional: pre-commit install runs ruff, the lock and fixture checks,
actionlint and gitleaks before each commit (.pre-commit-config.yaml; the
last two when installed).
A pull request is ready when ruff and the tests that cover the change pass,
plus both image builds when it touches data/, pyproject.toml or the
Dockerfile. The whole list above runs once before a release.
The docs site and its demo
Section titled “The docs site and its demo”The site (site/, Starlight) is built from this repository’s Markdown: README.md stays
GitHub’s front page, the site’s home page is site/pages/index.md, and every page’s address
and sidebar place come from SECTIONS in site/scripts/prepare.mjs. A Markdown file under
docs/ that isn’t placed there, or a broken link, fails the build. Images go in
docs/images/: the site serves them itself.
site/scripts/build-demo.sh # the demo character's pages; needs uv and Docker (or VL_BIN)npm --prefix site ci && npm --prefix site run buildnpm --prefix site run preview # http://localhost:4321/wow-mcp/build-demo.sh plays Nibbet, a made-up priest (tools/fixtures/generate.py --demo, seeded,
so every build plays the same evenings, shifted so his last one is yesterday), then runs the
product’s own publisher to build his public and friends’ pages under /demo/. Astro’s preview
server doesn’t map model3d/view to model3d/view.html the way GitHub Pages does, so View in
3D stays blank there.
The manual’s screenshots come from that demo, never from a real player:
uv run --extra render python site/scripts/screenshots.py <address of the built site> writes
docs/images/*.webp and the link preview docs/images/social.png; commit them.
.github/workflows/pages.yml builds the site on every push to main and deploys it to GitHub
Pages once the repository is public; before that, and on pull requests, the build is a
site-preview artifact.
Made-up data only
Section titled “Made-up data only”No test, fixture, doc or screenshot holds a real account, character, guild, host or address.
- Test fixtures come from
tools/fixtures/generate.py(seeded, byte for byte reproducible; its header lists what it writes). After changing it, or the code that derives the planner’s inputs:uv run python tools/fixtures/generate.py, read the diff, commit both. CI runs it with--check. - The demo is
dev/seed.py: five made-up characters with a DEMO DATA banner. Its header has the commands; the compose kit’s header has the two-line version. - The scan (
tests/test_public_scan.py) checks the shapes in git (no e-mail address, no private IP, no token-looking string) and, when a denylist file exists, every name in it. The denylist is never committed: one term per line in~/.config/wow-stats-public/denylist.txt, or the fileWOW_STATS_DENYLISTnames. Put your own names, characters, guild, domains and hosts in it.
CI in a fork
Section titled “CI in a fork”.github/workflows/ci.yml runs on GitHub-hosted runners with no secret: the
tests on Linux, the Windows installer test, the demo seed through
PowerShell’s pipe (5.1 and 7), both images with smoke tests (read-only
root, uid 10001), and the audit job (below). A fork gets all of it as is.
Three more workflows run only while the repository is public, because a private repository needs GitHub Advanced Security for them. Elsewhere they skip, which counts as passed for a required check:
| Workflow | What |
|---|---|
codeql.yml |
CodeQL on the Python and the JavaScript, results in the Security tab |
dependency-review.yml |
the dependencies a pull request adds or bumps: known vulnerabilities (moderate and up) and licenses that can’t ship with GPL-3.0-only |
scorecard.yml |
OpenSSF Scorecard, published to api.scorecard.dev and the Security tab |
Dependencies and supply chain
Section titled “Dependencies and supply chain”-
Updates: Dependabot (
.github/dependabot.yml), weekly on Monday: one grouped pull request per ecosystem (uv, GitHub Actions, the Dockerfile, the compose kit, the videos’ npm) for minor and patch bumps, one per major. A release has to be 7 days old before it’s proposed. Security updates come as soon as an advisory lands. -
Pins: actions by commit SHA with the tag in a comment, base images by tag and digest on literal
FROMlines (Dependabot doesn’t followARGs), Python packages byuv.lockwith hashes. The Python minor (3.15) moves by hand, not with the weekly bumps. -
Moved by hand:
POLESTAR_TAGinroute-reference.yml(kb-refresh’s watcher reports new Polestar releases), the renderer’s Debian snapshot date, and the Polestar Recorder version and checksum in the shipper. -
The
auditjob (CI, every push and pull request):actionlinton the workflows, with shellcheck on their scripts;uv lock --check:uv.lockin step withpyproject.toml;tools/audit_deps.py: pip-audit on every locked package, every extra and group. A known vulnerability fails the job;- gitleaks on the tree and every commit (
.gitleaks.toml: the default rules plus two proven false positives).
The same, locally:
Terminal window actionlintuv lock --checkuv run --frozen --only-group audit python tools/audit_deps.pygitleaks git --redact --config .gitleaks.toml . -
A vulnerability that can’t be fixed yet (no release upstream, or the vulnerable path is never reached): add it to
.github/vulnerability-allowlist.tomlwith the advisory id and a reason a reviewer can check. An entry without a reason fails the job. Remove it when the fix lands.
route-reference.yml reruns the route export when its inputs change, with
nothing to set up. kb-refresh.yaml needs a schedule and, for its model
pass, an Anthropic federation rule: docs/kb.md, “Running the
refresh job in your own repository”. Until then it runs only when you start
it by hand, and its model pass skips with a notice.
Releasing
Section titled “Releasing”- Bump
versioninpyproject.toml,__version__inwowstats/__init__.pyandVERSIONinshipper/wow_stats.py(a test keeps the three equal: every install’s shipper updates itself to a higherVERSION), write the CHANGELOG entry (what changed for a player, then “Upgrading” with every changed variable, port, volume or route), merge. - Run the full checks above on that commit, browsers included.
- Tag it
vX.Y.Zand push the tag..github/workflows/release.ymlbuilds both images for linux/amd64 and linux/arm64, pushesghcr.io/<owner>/wow-mcp:X.Y.Zandghcr.io/<owner>/wow-mcp-render:X.Y.Zand prints eachtag@digestin the run summary. The tag must matchpyproject.tomlor the run stops. Each platform builds on a runner of its own architecture (GitHub’subuntu-24.04-armfor arm64, no emulation), and a merge job joins them into one index per image.
A pull request that changes the Dockerfile, .dockerignore or
release.yml runs the same workflow as a dry run: both platforms build,
merge in a registry on the runner and pass the same checks. Nothing is
pushed.
Each image carries BuildKit’s SLSA provenance and an SPDX SBOM per platform, and the run keeps the SBOMs as an artifact. From a public repository the run also writes GitHub artifact attestations and a keyless cosign signature (below). From a private one those steps skip: artifact attestations need GitHub Enterprise Cloud there, and a signature would put the private repository’s name in Sigstore’s public log.
The image names live in one place, the env: block at the top of
release.yml. The owner part comes from the repository, so a fork publishes
to its own namespace. The builds stamp the repository’s URL in the
org.opencontainers.image.source label.
A package pushed from a private repository is private. Its visibility is set by hand in the package settings, never by the workflow.
Using a released image
Section titled “Using a released image”Pin by digest: ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:..., from the release
run’s summary.
While the package is private, every pull needs a token with
read:packages (a classic personal access token, or a GitHub App token
with that permission):
- Docker / compose:
docker login ghcr.io -u <user>with the token as the password (from stdin, never on the command line). Then indeploy/compose/.env:WOW_STATS_IMAGE=ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:..., anddocker compose pull ui publish site && docker compose up -d. - Kubernetes: a
kubernetes.io/dockerconfigjsonSecret forghcr.iowith that token, named in each pod’simagePullSecrets. The variables, ports and mounts are in docs/deploy.md.
Without WOW_STATS_IMAGE the compose kit builds the image from the tree
(docker compose up -d --build), so a clone runs with no registry at all.
Verifying an image
Section titled “Verifying an image”Releases from the public repository are attested and signed by
release.yml in that repository, on a v* tag. Replace <owner> with the
repository’s owner and X.Y.Z with the release.
Build provenance (which workflow, commit and tag built it), with the GitHub CLI:
gh attestation verify oci://ghcr.io/<owner>/wow-mcp:X.Y.Z --repo <owner>/wow-mcpgh attestation verify oci://ghcr.io/<owner>/wow-mcp-render:X.Y.Z --repo <owner>/wow-mcpThe SBOM attestations (one per platform), and the SBOM itself:
gh attestation verify oci://ghcr.io/<owner>/wow-mcp:X.Y.Z --repo <owner>/wow-mcp \ --predicate-type https://spdx.dev/Document/v2.3docker buildx imagetools inspect ghcr.io/<owner>/wow-mcp:X.Y.Z \ --format '{{ json (index .SBOM "linux/amd64").SPDX }}' > wow-mcp-amd64.spdx.jsonThe cosign signature, tied to the release workflow at a tag:
cosign verify ghcr.io/<owner>/wow-mcp@sha256:<digest> \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp '^https://github\.com/<owner>/wow-mcp/\.github/workflows/release\.yml@refs/tags/v'Pin what you verified by digest (ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:...):
a tag can move, a digest can’t.