# Contributing

Contributions that improve correctness, interoperability, performance, tests,
or documentation are welcome.

## Prerequisites

- A current MoonBit toolchain (`moon version`)
- Git

Clone the repository and verify the baseline:

```bash
git clone https://github.com/pei0331/moon-diff.git
cd moon-diff
moon fmt --check
moon check --deny-warn
moon test --target wasm-gc
```

## Development Workflow

1. Create a focused branch from `main`.
2. Add a regression test before or with each behavioral fix.
3. Preserve the public behavior of existing APIs unless the change is planned
   for a major release.
4. Run formatting, checks, builds, and tests before opening a pull request.

```bash
moon fmt
moon check --deny-warn
moon build --target wasm-gc
moon test --target wasm-gc
moon run examples/basic
```

## Test Expectations

- Cover empty input, prefix/suffix edits, repeated text, and multiline input.
- Include non-BMP input for changes that touch string indexing or slicing.
- For Unified Diff changes, assert the complete output including headers, hunk
  ranges, prefixes, and trailing newlines.
- Verify `reconstruct_old(diff(old, new)) == old` and
  `reconstruct_new(diff(old, new)) == new` for new diff cases.
- For script application changes, cover valid raw and compact scripts plus each
  `ApplyError` variant.

## Style

- Use `moon fmt`; do not hand-format generated `.mbti` files.
- Keep public APIs documented with MoonDoc comments.
- Prefer explicit behavior and deterministic edit ordering.
- Keep dependencies minimal and justify any new runtime dependency.

## Updating Public APIs

After changing exported declarations, regenerate interfaces and include them in
the same commit:

```bash
moon info
```

Update `README.md` and `CHANGELOG.md` whenever public behavior changes.

## Reporting Bugs

Include the old text, new text, actual edit script or patch, expected output,
MoonBit version, target backend, and a minimal reproduction when possible.