# Contributing to gasm-devkit

Thanks for contributing to gasm-devkit.

## Development setup

Requirements: Go 1.27 or later, the [just](https://github.com/casey/just)
command runner, and a Linux host on amd64, arm64, riscv64 or loong64.

```sh
git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
cd gasm-devkit
just install        # download module dependencies
just build          # go vet + gofmt check
just test           # full suite, race detector, 80 % coverage gate
```

## Workflow

1. Branch from `development`; never commit directly to `main` (`main` is
   release-only: merge from `development`, then tag).
2. Commit with [Conventional Commits](https://www.conventionalcommits.org/):
   `type(scope): description`: subject line only, imperative mood,
   lowercase after the colon, no trailing dot.  Allowed types: `feat`,
   `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`,
   `build`, `revert`.  The only line after the subject is the trailer:
   `Assisted-by: <model-name>`.  No `Co-Authored-By`, no `Signed-off-by`,
   no other trailers.
3. Record every user-visible change in `CHANGELOG.md` under
   `## [development]` (categories: Added, Changed, Fixed, Removed,
   Security).
4. Add or update tests; coverage must stay **at or above 80 %** (hard
   gate, enforced by CI).
5. Update the documentation when behaviour, flags or the public surface
   change.
6. Open a pull request against `development`.

Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`;
CI builds and publishes the binaries for all four architectures.

## Code style

`gofmt` and `go vet` via `just fmt` / `just build`; both must pass with
zero output; `go fix -diff ./...` must report nothing on touched packages.

- Standard library only in production code; `golang.org/x/arch` is used
  in tests only (round-trip decoding) and is never linked into the `gasm`
  binary.
- No cgo, no C, no external toolchains at runtime.
- Explicit `if err != nil`; errors wrapped with
  `fmt.Errorf("context: %w", err)`; no panics outside `main`.
- The parser, lexer and formatter are hand-written; the `arch` instruction
  tables are generated only via `_gen/gen.go` (`just gen`), never edited.

## Running a single test

```sh
go test -run TestVexGroundTruth ./asm/
go test -run TestGroundTruthBasic ./verify/
go test -run TestGOObjectLinkAndRun ./asm/
go test -run TestFuzzWideCopy ./verify/
```

The interactive debugger (`gasm debug`) requires a compiled binary on
`$PATH`; `go run` does not work for the traced child process.  Install
first with `just install-bin`.

## CI (Gitea Actions)

Workflows live in `.gitea/workflows/` and run on self-hosted runners:

| Workflow | Trigger | What it does |
|----------|---------|--------------|
| Test | push / PR to `development` | gofmt check, `go vet`, `go test -race`, 80 % coverage gate |
| Release | tag `v*` | cross-compiles binaries for linux/{amd64,arm64,riscv64,loong64} and publishes the Gitea release |

The Definition of Done (`just build` + `just test` + `just fmt`) must
still pass locally before pushing.

## AI Contribution Policy

AI tools are welcome as productivity aids.  What matters is that
contributions remain understandable, reviewable, and genuinely useful.

- **Disclose AI use.**  If you used AI to draft or generate any part of a
  commit, issue, pull request, or code review, say so clearly.
- **Commit messages:** end every commit with exactly one trailer:
  `Assisted-by: <model-name>` (e.g. `Assisted-by: GLM 5.3`).
- **Pull requests and issues:** attribute AI assistance in one trailing
  line, e.g. `_Assisted-by: GLM 5.3_`.  Do not paste it into the PR
  description as a section.
- **Take responsibility.**  You remain accountable for the accuracy,
  completeness, and intent of everything you submit.
- **Review before marking ready.**  Read AI-generated diffs carefully, run
  them locally, and add or update tests where appropriate.
- **Preferred models.**  Prefer open-weight models with transparent
  training data: **GLM**, **DeepSeek**, and **MiMo**.

## Reporting bugs

Open an issue at
[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues)
with the version (`gasm --version`), OS and architecture, the exact
command, the full output, and the expected versus actual behaviour.

**Security issues:** email **opensource@petrbalvin.org** instead of opening
a public issue.