gasm-sdk/CONTRIBUTING.md

# Contributing

Contributions to **gasm-sdk** 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 exact version the `go` directive in `go.mod`
declares, [just](https://github.com/casey/just) for the recipes, and a C
compiler (gcc), because `just gates` includes `just race` and the race
detector needs cgo.

```sh
git clone https://sourcedock.dev/petrbalvin/gasm-sdk.git
cd gasm-sdk
just build
just gates
```

## 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.
6. Update the documentation when the public API, the configuration or the behaviour
   changes.
7. Open a pull request against `development`.

Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The release
workflow builds the assets and publishes the release and its notes.

## Code style

`gofmt` and `go vet` run through `just fmt` and `just vet`, with zero diff and zero
warnings tolerated. `just vet` is two gates, `go vet ./...` and `go fix -diff ./...`,
so the modernisation rewrites are enforced too. `just gates` is the definition of done in
one command, and the recipe file names what it contains. Errors are checked explicitly,
wrapped as `fmt.Errorf("context: %w", err)`, and nothing panics outside `main`. The
recipe file holds the commands, and the language and standard-library surface is the one
the `go` directive in `go.mod` pins.

- `golang.org/x/arch` is the one module dependency, and it is linked into the binary:
  `gasm dis` and the debugger's listings decode through it. Everything else is the
  standard library.
- No cgo and no C. The standalone encoder paths (`gasm asm --format raw` and `--format
  elf`) need no Go installation; `gasm verify --ground-truth`, `gasm verify --fuzz`,
  `gasm audit-instructions` and `gasm asm --format goobj` resolve through the installed
  Go toolchain.
- The parser, lexer and formatter are hand-written; the `arch` instruction tables are
  generated only by `_gen/gen.go` (`just gen`) and never edited by hand.
- Assembly committed to the repository goes through `gasm fmt` and `gasm lint`, so a
  `.s` file that `gasm fmt -l .` lists is unfinished.

New source files open with the project's two-line 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**, as a git trailer on the line after a
  blank line that closes 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` | the format check, `go vet`, and the short layer of the test suite with the coverage profile and the 80 % floor, inside the two-minute budget |
| Suite | dispatched by hand | the complete gate set minus race: the build, both static gates, the full suite and the coverage floor |
| FreeBSD build | dispatched by hand | the three FreeBSD compile gates for amd64, arm64 and riscv64 |
| Release | a `v*` tag | the matrix build, the version smoke test and the release with its assets; no gate runs at the tag |

The local equivalent is `just gates`, which is the same set plus the race detector. Race
never runs in CI, on a push or a tag: it would double the time and the memory a shared
runner cannot spare, so the local `just gates` runs it before the tag is cut.

## Reporting bugs

Open an issue at `https://sourcedock.dev/petrbalvin/gasm-sdk/issues` with the
version, the operating system and architecture, the exact command, the full output,
and the expected against the actual behaviour.

**Security issues do not go in the issue tracker.** Report them as
[SECURITY.md](SECURITY.md) describes, to **opensource@petrbalvin.org**.