interpres/CONTRIBUTING.md

# Contributing

Thanks for contributing to **interpres**.

## Development setup

Requirements: Go 1.27.0, the version `go.mod` declares, and
[just](https://github.com/casey/just) for the recipes.

```sh
git clone https://sourcedock.dev/petrbalvin/interpres.git
cd interpres
just build
just test
```

## Workflow

1. Branch from `development`. Never commit directly to `main`, which is
   release-only.
2. Commit in [Conventional Commits](https://www.conventionalcommits.org/) form:
   `type(scope): description`, subject line only, imperative mood, lowercase
   after the colon, no trailing full stop. Allowed types: `feat`, `fix`, `docs`,
   `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`.
3. One logical change per commit. A refactor, a behaviour change and a
   formatting pass are three commits, never one.
4. Record every user-visible change in `CHANGELOG.md` under `## [development]`.
5. Add or update tests. Coverage stays at 80 percent or more; it is a hard
   gate. Parser and decoder changes must also keep the toml-test suite at zero
   failures, checked with `just toml-test`.
6. Update the documentation when the public API, the configuration or the
   behaviour changes; the documents move in the same commit as the behaviour
   they describe.
7. Open a pull request against `development`.

Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The
release workflow runs the full gate set including the race detector and
publishes the Gitea release with the matching `CHANGELOG.md` section as its
notes.

## Code style

The project is standard library only: no third-party Go module enters `go.mod`,
because that constraint is the point of the project.

The formatter is `gofmt` and the linters are `go vet` and `go fix -diff`, run
through the recipes: `just fmt` formats in place, `just fmt-check` demands a
zero diff, `just vet` runs both static gates, and `just gates` is the
definition of done in one command. Errors are checked explicitly and wrapped as
`fmt.Errorf("context: %w", err)`; nothing panics outside `main`. Tests are
table-driven and live next to the code they cover.

New source files open with the project's two-line MIT licence header, whose
SPDX identifier matches `LICENSE`. Configuration files, workflows and dotfiles
do not carry it.

## AI contribution policy

AI tools are welcome as productivity aids and are a normal part of modern
software development. What matters is that the contribution stays
understandable, reviewable and genuinely useful.

- **Disclose the assistance.** If AI helped draft any part of a commit, issue,
  pull request or review, say so.
- **Commit messages carry exactly one trailer**, on the line after the subject:

  ```
  Assisted-by: MODEL
  ```

  Name the model that did the work, spelled the way its maker spells it, for
  example `GLM 5.3`, `DeepSeek V4.1 Flash` or `Qwen 3.8 Flash`. No
  `Co-Authored-By`, no `Signed-off-by`, no other trailers, and no prose: the
  trailer is the disclosure.
- **Issues and pull requests** attribute the assistance in a comment, for
  example `_Assisted-by: GLM 5.3_`. It does not belong in the pull request
  description.
- **Take responsibility.** You are accountable for the accuracy, completeness
  and intent of everything you submit, whether or not AI produced it.
- **Review before marking ready.** Read the diff carefully, run it locally, and
  add the tests it needs. Do not mark a pull request ready until you can defend
  every change in it.
- **Quality over quantity.** Contributions that look like un-reviewed output,
  or whose author cannot engage substantively during review, may be closed.
- **Preferred models.** Prefer open-weight models with transparent training
  data and minimal output filtering.

AI assists. It does not replace judgement.

## Continuous integration

Workflows live in `.gitea/workflows/` and run on the project's own runners:

| Workflow | Trigger | What it does |
|---|---|---|
| Test | push or pull request to `development` | format check, vet, modernisation, build, the test suite with the coverage floor, the toml-test compliance suite |
| Race | `workflow_dispatch`, by hand | the suite under the race detector, the same race gate the local `just gates` runs |
| Release | a `v*` tag | the same gates plus the race detector, then the Gitea release created from the `CHANGELOG.md` section |

The local equivalent is `just gates`, which is the same set plus the race
detector.

## Reporting bugs

Open an issue at `https://sourcedock.dev/petrbalvin/interpres/issues` with the
version, the operating system and architecture, the exact command, the full
output, and the expected against the actual behaviour. For a parser bug, the
smallest TOML document that triggers it decides how fast it is fixed.

**Security issues do not go in the issue tracker.** Report them as
[SECURITY.md](SECURITY.md) describes.