# Contributing to annotation-editor Thanks for helping out! Open an issue before starting anything large so we can agree on the approach first. By participating you agree to follow our [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues go through the [Security Policy](./SECURITY.md), **not** public issues. ## Ways to contribute - **Report a bug** — use the _Bug report_ issue form. A minimal example that reproduces the problem helps a lot. - **Suggest a feature or improvement** — use the _Feature request_ or _Improvement_ form. - **Improve the docs** — everything under `docs/guide/` is fair game. - **Send a pull request** — for bugs, small improvements, or anything already agreed on in an issue. ## Development setup Requirements: **Node 24** and **pnpm** (version pinned in `package.json` → `packageManager`; `corepack enable` picks it up). ```sh git clone https://github.com/GhentCDH/annotation-editor.git cd annotation-editor pnpm install pnpm nx run-many -t build # build all packages pnpm nx run-many -t test # unit tests pnpm nx run-many -t lint # lint (CI fails on lint errors — typecheck does not catch them) pnpm nx run-many -t typecheck pnpm nx run docs:serve # docs site on localhost ``` This is an [Nx](https://nx.dev) monorepo — always run tasks through `pnpm nx`, and prefer `pnpm nx affected -t lint test` while iterating. ## Where does code go? | Package | Contains | | ------------------- | ----------------------------------------------------- | | `annotation-core` | Shared schemas, types and utilities. No Vue, no Nest. | | `annotation-api` | NestJS backend module | | `annotation-editor` | Editor UI (private, bundled into `annotation-vue`) | | `annotation-ui` | Shared Vue UI pieces (private) | | `annotation-vue` | Published Vue bundle | ## Code style - Formatting is Prettier (`singleQuote`); ESLint enforces import order and type-only imports. - The pre-commit hook runs lint on affected projects; `pnpm nx run-many -t lint --fix` fixes most findings. ## Commits and pull requests - Branch from `main`. - Use [Conventional Commits](https://www.conventionalcommits.org/) with the package as scope, e.g. `fix(api): …`, `feat(core): …`, `refactor(core,api): …`, `docs: …`. Mark breaking changes with `!` (`refactor(core)!: …`). - PR titles follow the same format — they end up in the release notes. - Keep PRs focused; one logical change per PR. - Add or update tests, and update `docs/guide` for user-facing changes. - Fill in the pull request template. ## Releasing (maintainers) ```sh pnpm release prerelease --preid rc # next release candidate: 0.1.0-rc.0 → 0.1.0-rc.1 pnpm release 0.1.0 # exact version, e.g. the final release ``` Run it on an up-to-date `main` with a clean working tree. The release commit and tag are pushed straight to `main`: with the rulesets active (`.github/rulesets`), only the `ghentcdh-developers` team can do that. The newest `v*` tag is always the base, whatever its preid (`release.releaseTag.strictPreid: false` in `nx.json`): the version is bumped from it and the changelog lists the commits since it. Do not use `--first-release`: it builds the changelog as if no earlier release existed. `RELEASE_NOTES.md` lists `feat`, `fix`, `perf` and `refactor` commits. Mark breaking changes with `!` on one of those types (`refactor(core)!: …`) and explain the migration in a `BREAKING CHANGE:` footer; a breaking change in a `chore:`, `test:` or `ci:` commit does not show up. Prereleases are published under the npm dist-tag `rc` (`-rc.N`) or `alpha` (any other preid), never `latest`. A plain version (`0.1.0`) becomes `latest`. What happens: 1. **On your machine** (`release` script = `nx release --skip-publish`): builds, bumps the package versions, updates `RELEASE_NOTES.md`, commits `chore(release): publish ` and tags `v`. Nothing is published and no GitHub release is created. 2. **`postrelease` script**: `git push --follow-tags --atomic` pushes the commit and the tag. 3. **On GitHub**, triggered by the tag: - `Publish`: publishes the packages to npm (trusted publishing, no token) and creates the GitHub release. Its notes are generated by GitHub from the merged pull requests, grouped by label (`.github/release.yml`), so PR titles and labels are what readers see. - `Publish Docs`: builds and deploys the documentation site. Check the `Publish` run afterwards: it fails if a package could not be published, and the release notes list which packages made it. ### Use the script, not `nx release` directly `npx nx release …` skips the two things the script adds: - It asks **"Do you want to publish these versions?"**. Answer **No**: "Yes" publishes from your machine instead of from the workflow. Never pass `--yes`, it answers "Yes" for you. (`--skip-publish` cannot be set in `nx.json`, only on the command line, which is why it lives in the script.) - It does not push. Run `git push --follow-tags --atomic` yourself afterwards. ### Try it first ```sh pnpm nx release prerelease --preid rc --skip-publish --dry-run ``` shows the new version and changelog entry without changing anything. ### Undo a release that is not pushed yet The commit and tag only exist locally until the push. To drop the last one: ```sh git tag -d v git reset --hard HEAD~1 ``` Once the tag is pushed the release is out: fix forward with a new release instead. ## License By contributing, you agree that your contributions are licensed under the [MIT License](./LICENSE).