# Contributing

All project text (code, comments, commit messages, docs) is **English**.

## Development

```bash
npm install
npm run typecheck
npm run lint
npm test
npm run build
npm run demo
```

`npm run demo` opens the playground at `http://localhost:5173`. `npm run demo:build` produces the GitHub Pages bundle.

The navigation core (`src/core`) must stay framework-agnostic: no React imports, and unit tests must not need a real browser or a live Mermaid render.

## Pull requests

`main` is not a direct-push branch for regular contributors.

- Open a pull request.
- Wait for the **`ci`** GitHub Actions job (typecheck, lint, test, build).
- Get **at least one approving review**.
- Resolve **all** review conversations.
- Keep the branch **up to date** with `main` before merge.

Force pushes and branch deletion on `main` are blocked. Only a repository **admin/owner** may bypass these rules, and only when strictly necessary.

## Repository ruleset (intent)

The ruleset in [`docs/github-ruleset.json`](./docs/github-ruleset.json) encodes:

| Rule | Intent |
| --- | --- |
| Require a pull request | No direct pushes to `main` |
| 1 approving review | Changes are reviewed |
| Required status check `ci` | Typecheck, lint, test, and build must pass |
| Strict status checks | Branch must be up to date with `main` |
| Require conversation resolution | Unresolved threads cannot merge |
| Block force pushes | `non_fast_forward` on `main` |
| Block deletions | `main` cannot be deleted |
| Admin bypass | Repository admin role + organization admin |

Apply or update it with:

```bash
gh api --method POST repos/inclunet/mermaid-a11y/rulesets --input docs/github-ruleset.json
```

If a ruleset with the same name already exists, update it by id instead of creating a second copy:

```bash
gh api repos/inclunet/mermaid-a11y/rulesets --jq ".[] | {id,name}"
gh api --method PUT repos/inclunet/mermaid-a11y/rulesets/RULESET_ID --input docs/github-ruleset.json
```

GitHub’s UI path: **Settings → Rules → Rulesets**. Prefer the JSON above so the policy stays reviewable in git.

## Releases

1. Bump `version` in `package.json`.
2. Merge to `main` through a PR.
3. Create a GitHub Release (tag `vX.Y.Z`). The **Publish** workflow publishes `@inclunet/mermaid-a11y` to npm.

Never commit secrets. `NPM_TOKEN` lives only as a repository secret.