Skip to content

Contributing

  1. Fork and create a feature branch.
  2. Follow Conventional Commits (feat:, fix:, chore:, …) — subject ≤ 72 chars, body ≤ 10 lines.
  3. Run make code-standard before opening a PR.
  4. Changes under server/src/main/ require a new or updated test in server/src/test/.
  5. New user-visible strings go in both data/config/i18n/en.yaml and fr.yaml.
  6. Update the relevant JSON Schema in server/src/main/resources/schemas/ in the same commit as a YAML-backed data-class change (make gen-schemas, checked by make check-schemas).
  7. After changing a data/config/*.yaml default or a *Constants value, run make docs so the reference tables stay in sync (checked by make check-docs).

Editing the docs site

  • Pages: docs/**, nav: docs/SUMMARY.md, config: mkdocs.yml.
  • Preview: make docs-site-serve → http://localhost:8000.
  • Strict build: make docs-site-build.
  • The Releases, Slash commands and API routes pages are generated at build time by scripts/docs/gen_docs.py — edit the source (README.md), not the rendered page.

Component screenshots

Drop a tag on its own line to embed a Storybook snapshot of a component. The id is the value in Storybook's URL (?path=/story/<id>); a leading story/ is optional:

<figure class="story-shot" markdown="span">
  ![Game/Layout/PlayerStatusBar — Caster](assets/stories/game-layout-playerstatusbar--caster.png){ loading=lazy }
  <figcaption>Game/Layout/PlayerStatusBar — Caster · <a href="https://github.com/micoli/micraft/blob/main/app/webApp/ts-src/.stories/game/layout/PlayerStatusBar.stories.tsx">source</a></figcaption>
</figure>
<figure class="story-shot" markdown="span">
  ![…](assets/stories/game-layout-playerstatusbar--warrior.png){ loading=lazy }
  <figcaption>… · <a href="https://github.com/micoli/micraft/blob/main/app/webApp/ts-src/.stories/game/layout/PlayerStatusBar.stories.tsx">source</a></figcaption>
</figure>

scripts/docs/hooks.py rewrites the tag to a <figure> pointing at a committed PNG under docs/assets/stories/ (caption defaults to the story's title/name).

The PNGs and app/webApp/ts-src/.storybook/stories-manifest.json are generated by make docs-screenshots (headless Chromium via app/webApp/ts-src/scripts/screenshot-stories.mjs) and committed — the docs CI has no browser. Run it after adding a tag or changing a referenced story. make check-docs-screenshots (run in ci.yml) fails on a stale manifest, a missing PNG, or an orphan PNG (pixels aren't diffed — they're not reproducible across machines). A tag pointing at an unknown story or a missing PNG also fails the strict make docs-site-build.

Credits