Contributing to gasm-devkit

Prerequisites

Go 1.26 or later (toolchain go1.26.5)
just command runner
A Linux host on amd64, arm64, riscv64 or loong64

Development Setup

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

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:

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

Code Style

See 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 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.

3.0 KiB Raw Blame History