interpres/CONTRIBUTING.md

# Contributing

Contributions to **interpres** are governed by the Contributor terms
below; submitting one means you accept them.

## Contributor terms

1. This project belongs to its owner alone. The owner decides what is
   accepted, in what form and when; the decision is final and needs no
   justification.
2. By submitting a contribution you assign to Petr Balvín
   <opensource@petrbalvin.org> all present and future copyright and
   related rights in it, worldwide, for the full term of the rights,
   with the right to relicense and sublicense without restriction,
   including under proprietary terms.
3. Where that assignment is not effective, it counts as a perpetual,
   irrevocable, royalty-free licence with the same scope.
4. To the fullest extent permitted by law, you waive any right of
   attribution and integrity in the contribution. The project names no
   contributors and keeps no credits list.
5. By submitting you represent that the work is yours and that you
   hold the rights to assign it as above.

## Development setup

Requirements: Go 1.27.1, 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, decoder and encoder changes must also keep both directions of
   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 validates the tag, runs the static gates and the test suite
with the coverage floor, and publishes the Gitea release with the matching
`CHANGELOG.md` section as its notes. The race detector is not in that set: race
never runs on a push path, and the local `just gates` raced the tree before the
tag was cut.

## 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 | tag validation, format, vet, modernisation, build and the test suite with the coverage floor, then the Gitea release created from the `CHANGELOG.md` section; no race detector |

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.