# Contributing to gasm-devkit

## Prerequisites

- Go 1.27 or later (`toolchain go1.27.0`)
- `just` command runner
- A Linux host on amd64, arm64, riscv64 or loong64

## Development Setup

```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 test suite with race detector
```

## Commands

Every just recipe:

| Recipe | What it does |
|--------|-------------|
| `just` | List all recipes |
| `just install` | `go mod download` |
| `just build` | `go vet ./...` + `gofmt -l .` check — zero errors required |
| `just test` | `go test -race -count=1 -coverprofile=coverage.out ./...` + 80 % coverage gate |
| `just fmt` | `gofmt -w .` |
| `just run -- lint file.s` | Run the CLI with `go run` (args after `--`) |
| `just install-bin` | Install `gasm` into `$GOBIN` with the release version stamped |
| `just gen` | Regenerate `arch/*_gen.go` instruction tables from the Go toolchain |
| `just uninstall` | Remove build artefacts (`coverage.out`, `gasm`, `*.test`) |

## Running a Single Test

```sh
go test -run TestVexGroundTruth ./asm/
go test -run TestDifferentialLZ4Fuzz ./verify/
```

## Testing the Debugger

The interactive debugger (`gasm debug`) requires a compiled binary —
`go run` does not work for the child process. Install first:

```sh
just install-bin
gasm debug --func add testdata/verify/basic_amd64.s
```

## Code Style

See [AGENTS.md](AGENTS.md) for the full style guide. Key points:

- `gofmt` — zero diff.
- `go vet` — zero warnings.
- Standard library only in production code; `golang.org/x/arch` in tests.
- No cgo, no C, no JavaScript.
- Hand-written Plan 9 assembly; tables generated only via `_gen/gen.go`.

## Branches and Releases

- `development` is the working branch.
- `main` is release-only: `git merge --ff-only development`, then `git tag vX.Y.Z`.
- Conventional Commits: `feat(asm): add EVEX gather and scatter`.
- Every commit ends with `Assisted-by: <model-name>`.

## CI

CI runs on every push to `development` and on pull requests:

- **Test** (`test.yml`) — `gofmt` check, `go vet`, `go test -race` and the
  80 % coverage gate.
- **Release** (`release.yml`) — cross-compiles release binaries for
  linux/{amd64,arm64,riscv64,loong64} on version tags and publishes them.

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

## AI-Assisted Contributions

AI agents may assist with code, documentation, tests, and review. All
AI-assisted changes must:

- Include the trailer `Assisted-by: <model-name>` in the commit message
  (e.g. `Assisted-by: DeepSeek V4 Pro`).
- Follow the [AGENTS.md](AGENTS.md) rules.
- Pass the Definition of Done before committing.

Attribute agent authorship in issues and pull requests on one trailing
line:

```
_Assisted-by: Qwen 3.8 Max_
```

## Questions

Open an issue at
[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues).