gasm-sdk/CONTRIBUTING.md

Contributing to gasm-devkit

Thanks for contributing to gasm-devkit.

Development setup

Requirements: Go 1.27 or later, the just command runner, and a Linux host on amd64, arm64, riscv64 or loong64.

git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
cd gasm-devkit
just build          # compile, zero errors and zero warnings
just gates          # build, fmt-check, vet, test, race: the definition of done

Workflow

1. Branch from development; never commit directly to main (main is release-only: merge from development, then tag).
2. Commit with Conventional Commits: 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 vet; 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

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.

CI (Gitea Actions)

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

Workflow	Trigger	What it does
Test	push / PR to development	the gates set minus race: gofmt, go vet, go fix, build, the suite, the 80 % coverage floor
Race	manual dispatch, and inside the release	the suite under the race detector
Release	tag v*	the gates once, then cross-compiles binaries for linux/{amd64,arm64,riscv64,loong64} and publishes the Gitea release

The Definition of Done (just gates) 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 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.