# Contributing

Contributions are welcome. The repository is a pnpm workspace with the published package in
`packages/starlight-quiz` and this documentation site (which doubles as the test fixture) in `docs`.

## Set up

Node ≥ 22.12 and pnpm are required.

```sh
git clone https://github.com/ewels/starlight-quiz
cd starlight-quiz
pnpm install
pnpm dev        # run the docs site locally
```

## Checks

| Task                       | Command                          |
| -------------------------- | -------------------------------- |
| Unit tests (Vitest)        | `pnpm test`                      |
| End-to-end tests (Playwright) | `pnpm test:e2e`               |
| Type-check                 | `pnpm typecheck`                 |
| Lint · format              | `pnpm lint` · `pnpm format`      |
| Everything (as CI runs it) | `prek run --all-files`           |

`prek install` wires the git pre-commit hook (prettier → eslint → typecheck); CI runs the same `prek run --all-files`.

:::note[MDX is formatted by hand]
Prettier is **not** run on `.mdx` files. It reflows task lists and fenced quiz examples in ways that break the
authoring syntax. Format MDX manually.
:::

## Translations

Translations are gettext `.po` files in `packages/starlight-quiz/locales/`, shared verbatim with
[mkdocs-quiz](https://github.com/ewels/mkdocs-quiz) so both plugins stay in sync. See
[Contributing translations](/starlight-quiz/guides/contributing-translations/) for how to add or improve a language.

## Releases

Notable changes are added under the **Unreleased** heading at the top of
[`CHANGELOG.md`](https://github.com/ewels/starlight-quiz/blob/main/CHANGELOG.md), in the same PR as the change.

To cut a release:

1. Move the **Unreleased** entries into a new `## **Version X.Y.Z** (YYYY-MM-DD)` section, and bump `version` in
   `packages/starlight-quiz/package.json` to match.
2. Commit and push to `main`.
3. Publish a [GitHub release](https://github.com/ewels/starlight-quiz/releases/new) with a tag matching the version
   (e.g. `v1.0.0`).

Publishing the release triggers the [Release workflow](https://github.com/ewels/starlight-quiz/blob/main/.github/workflows/release.yml),
which publishes to npm via trusted publishing (no token to manage). It first checks that the release tag matches the
package version, so a mismatch fails the run rather than shipping the wrong version.

:::note[First publish is manual]
npm trusted publishing can only be configured on a package that already exists, so the very first release is published
by hand (`pnpm release` after `npm login`). After that, add the GitHub repository as a trusted publisher in the package
settings on npmjs.com, and every later release publishes automatically.
:::