gasm-sdk/CONTRIBUTING.md

Contributing to gasm-devkit

Prerequisites

• Go 1.27 or later (toolchain go1.27rc1)
• 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.