​

PR Checklist

Checklist for releasing a new PR against this repo. Merges to main auto-deploy to production via the Mintlify GitHub App — there is no separate build/release step, so everything here should happen before merging, not after.

​

1. Local setup

• npm ci (installs the pinned mintlify CLI version from package-lock.json). Using a stray global/cached npx mint instead of the pinned version can silently run an older CLI missing commands (e.g. mint validate) — always npm ci first in a fresh clone or after pulling package.json changes.

​

2. Content correctness

• Verify any new/changed API behavior, limit, or guarantee is actually true in the running system before documenting it (check the source repo / infra, don’t guess).
• No personal names in customer-facing content — use neutral phrasing.
• Reuse an existing snippet from snippets/ instead of duplicating prose, if one exists.
• New .mdx page? Confirm it’s registered in docs.json nav (or intentionally left as an orphan page linked from elsewhere, matching this repo’s existing pattern for per-metric/event sub-pages).
• Renamed/moved a page? Update its docs.json entry and any redirects in the same change.

​

3. Automated checks (mirrors .github/workflows/pr-checks.yml)

Run these locally before pushing — CI runs them again on the PR, but catching failures locally is faster than round-tripping through Actions:

• npx mint validate — strict build validation (bad frontmatter, pages missing from nav, MDX parse errors).
• npx mint broken-links — fails on any broken internal link.
• npx mint openapi-check api-reference/openapi.json — only meaningfully changes if the spec was touched, but cheap to run every time.
• npx -y cspell@8 "**/*.{mdx,md,py}" --no-progress --gitignore — spellcheck. Add real domain terms to cspell.json’s words list rather than ignoring the file; don’t add actual typos there.

​

4. Repo-specific tasks

• If api-reference/openapi.json changed: restart npx mint dev locally (hot reload doesn’t pick up spec changes) and re-check the API reference pages render correctly.
• If any biomechanics movement page listed in scripts/MOVEMENT_PAGES changed (or a page/metric/event it links to changed): rerun python3 scripts/export_movements.py to refresh docs-exports/ (git-ignored, so this won’t show in git status — it’s a local artifact, but staleness here is exactly what caused broken links previously).
• Preview locally with npx mint dev and click through the actual changed pages — type checking/link checking verifies structure, not whether the page reads well or renders as intended.

​

5. Review before pushing

• git status / git diff review of everything staged — no secrets, no unrelated files, no accidental docs-exports/ or node_modules/ additions.
• Generate a PR summary describing every changed/added/removed file and why (see below) — use it as the PR description.

​

6. PR summary generation

Before opening the PR, produce a summary covering:

• Every added, modified, and deleted file (git status --porcelain covers untracked + tracked; git diff --stat covers tracked-file line counts).
• A one-line description of why each file/group of files changed, not just what.
• Group related files (e.g. “23 new softball pitching metric pages”) rather than listing every file individually when there are many similar additions.

​

7. After merge

• Confirm the Mintlify deploy succeeded (no build step to watch locally — check the live site or the Mintlify dashboard).
• If docs-exports/ was regenerated locally, no action needed — it’s git-ignored and not part of the deploy.