# Contributing to Chord

Thanks for your interest in contributing!

This repository is intended for open-source contributors. Development can be done with standard Go tooling.

## Prerequisites

- Go 1.26.3+
- Go quality tools:

```bash
go install golang.org/x/tools/cmd/goimports@latest
go install golang.org/x/tools/gopls@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
```

## Build

```bash
go build ./...
```

Enable commit hooks once:

```bash
./scripts/setup-git-hooks.sh
```

This installs `.githooks/pre-commit`, which runs `goimports` and `gofmt` on staged `.go` files before each commit.

## Run

```bash
go run ./cmd/chord/
```

## Test

Before submitting a PR, run the same entry point CI uses locally:

```bash
make ci
# or, for the test/coverage job only:
scripts/check_ci_local.sh
```

The Makefile targets mirror CI and should be preferred over copying individual commands by hand. Useful focused targets:

```bash
make fmt-check
make test-cover    # CI requires total coverage >= 70.0%.
make race
make vet
make staticcheck
make gopls-check
make docs-check
```

If your changes touch TUI performance-critical paths, also run:

```bash
./scripts/bench_tui_regression.sh
```

Optional integration tests that require external tools are not part of the default CI run. To run the real Pyright LSP integration test locally, install `pyright-langserver` and run:

```bash
CHORD_RUN_REAL_PYRIGHT_TESTS=1 go test ./internal/tools -run Pyright
```

## Scope & style

- Keep PRs small and focused
- Avoid unrelated refactors in the same PR
- When changing behavior, add or update unit/regression tests.
- If tests are impractical for a change, provide clear minimal verification steps in the PR.
- When changing user-facing behavior, CLI flags, configuration, workflows, or documented development commands, update the relevant docs.

## Documentation

- User-facing docs live under `docs/` as bilingual markdown (`*.md` for English, `*_CN.md` for Chinese). They remain readable on GitHub directly.
- A Starlight (Astro) site under `website/` renders the same markdown into the public docs site. Source of truth stays in `docs/`; the site is generated by `scripts/sync-docs.mjs`.

To preview doc changes locally:

```bash
cd website
npm install        # first time only
npm run dev        # http://localhost:4321/chord/
```

`npm run dev` runs the sync script first, so any edits under `docs/` show up after a refresh. Do **not** edit files under `website/src/content/docs/{en,zh}/` directly — they are gitignored and regenerated on every build.

When you add a new top-level page under `docs/`, also list it in:

- `docs/index.md` and `docs/index_CN.md` (the per-section navigation),
- `website/astro.config.mjs` (the Starlight sidebar) — add an entry under the right group with both English label and `zh-CN` translation.

The docs site is automatically built and deployed by `.github/workflows/docs.yml` whenever `docs/`, `website/`, `scripts/sync-docs.mjs`, or the README files change on `main`.

## Security

If you discover a security issue, please open a [GitHub security advisory](https://github.com/keakon/chord/security/advisories/new) with reproduction steps and impact details.
