docs: document set and changelog
Assisted-by: GLM 5.3 Flash
This commit is contained in:
+111
@@ -0,0 +1,111 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user