# Contributing to Spicy Lyrics TTML Tool

Thanks for helping. Keep changes focused, tested, and easy to review.

## Setup

Use Node.js LTS, pnpm, and Rust/Cargo for desktop work. pnpm is mandatory;
do not use npm or Yarn.

```bash
pnpm install
pnpm dev          # web app
pnpm tauri dev    # desktop app
```

Run a production build before opening a PR that changes UI, dependencies,
configuration, or Tauri code:

```bash
pnpm run build
```

## Project layout

- `src/components` contains shared UI.
- `src/modules` contains feature-specific UI and logic.
- `src/states` contains shared Jotai atoms.
- `src-tauri` contains the Rust/Tauri desktop app.
- `src/i18n/locales/<lang>/translation.json` contains the UI translations.
- `changes` contains one note per unreleased user-visible change.

Keep feature-local state in its module. Put state shared by unrelated features
in `src/states`.

## Code, tests, and translations

- Add or update focused Vitest coverage for non-trivial behavior changes.
- Check only the files you changed before committing:

  ```bash
  pnpm exec biome check <changed files>
  ```

- Do not run a broad formatter over unrelated files. Do not hand-edit
  `pnpm-lock.yaml`.
- Use the existing i18next pattern for new user-facing strings when practical.
  Add new keys to every locale and run `pnpm test:locales`, which fails on
  missing, unused or out-of-order keys. Do not make bulk locale rewrites
  unless the change requires them.

## Pull requests

Branch from `dev` and target `dev`; `main` only receives releases. Explain
what changed, why, and how you tested it.
Include screenshots for visual changes and clear reproduction steps for bug
fixes. Do not mix refactors with unrelated feature work.

Every user-visible feature or fix needs a note in `changes/<short-slug>.md`
(format in [`changes/README.md`](changes/README.md)). CI fails without one;
PRs with no user-visible change get the `no-changelog` label instead. Notes are
compiled into `src/data/changelog.json` at release time, and GitHub Release
notes are generated from it.

## Releases and distribution

Releases are maintainer-only and use stable Semantic Versioning (`X.Y.Z`). Use
the bump type that describes compatibility and functionality, not how many
lines changed:

- **Patch** (`0.7.7` to `0.7.8`): bug fixes, performance fixes, and small
  refinements that do not add a new capability or break existing behavior.
  Several fixes may be grouped into one patch release.
- **Minor** (`0.7.8` to `0.8.0`): new backward-compatible features or
  substantial new capabilities.
- **Major** (`0.8.0` to `1.0.0`): breaking compatibility, or declaring the
  first stable `1.0.0` release.

Do not use letter suffixes such as `0.7.6a`; they are not valid SemVer. SemVer
prerelease forms such as `0.8.0-alpha.1`, `0.8.0-beta.1`, and `0.8.0-rc.1` are
reserved for a future prerelease channel and are not supported by the current
stable release workflow.

### Make a release

Use this exact order for every new version. For example, a fix after `0.7.7`
uses a patch bump to `0.7.8`; a new feature uses a minor bump to `0.8.0`.

1. Preview the bump, then update every version file together:

   ```bash
   pnpm version:bump patch --dry-run
   pnpm version:bump patch
   ```

   Replace `patch` with `minor` or `major` when appropriate. The command
   updates `package.json`, `src-tauri/tauri.conf.json`,
   `src-tauri/Cargo.toml`, and the app entry in `src-tauri/Cargo.lock`.
2. Compile the pending `changes/` notes into `src/data/changelog.json`
   (preview first). This deletes the compiled notes:

   ```bash
   pnpm changelog:compile --version 0.7.8 --summary "Short summary" --dry-run
   pnpm changelog:compile --version 0.7.8 --summary "Short summary"
   ```
3. Run the relevant tests, `pnpm exec biome check <changed files>`, and
   `pnpm run build`.
4. Commit and push the version and changelog changes.
5. Create and push exactly one matching tag:

   ```bash
   git tag -a v0.7.8 -m "Release v0.7.8"
   git push origin v0.7.8
   ```

6. Wait for the **Build desktop app** GitHub Action. It creates the permanent
   GitHub Release, updater manifest, installers, and Winget submission PR.
7. Check that the release has `latest.json` and the Windows x64 `.msi` before
   announcing it.

Never reuse, move, or overwrite an existing release tag. If a release fails,
fix the workflow or source in a new commit and ask a maintainer how to recover
the affected release.

Do not create release tags, change updater signing keys, change updater release
endpoints, or alter Winget publishing secrets/workflows without maintainer
approval. Tagged releases publish immutable GitHub assets; ordinary branch
builds are GitHub Actions artifacts only.

Winget manifests are generated from `winget/package.json` and submitted by CI.
Do not edit generated manifests in the Winget fork by hand.