gasm-sdk/CONTRIBUTING.md

Contributing

Contributions to gasm-devkit are governed by the Contributor terms below; submitting one means you accept them.

Contributor terms

1. This project belongs to its owner alone. The owner decides what is accepted, in what form and when; the decision is final and needs no justification.
2. By submitting a contribution you assign to Petr Balvín opensource@petrbalvin.org all present and future copyright and related rights in it, worldwide, for the full term of the rights, with the right to relicense and sublicense without restriction, including under proprietary terms.
3. Where that assignment is not effective, it counts as a perpetual, irrevocable, royalty-free licence with the same scope.
4. To the fullest extent permitted by law, you waive any right of attribution and integrity in the contribution. The project names no contributors and keeps no credits list.
5. By submitting you represent that the work is yours and that you hold the rights to assign it as above.

Development setup

Requirements: Go 1.27.1, the exact version the go directive in go.mod declares, just for the recipes, and a C compiler (gcc), because just gates includes just race and the race detector needs cgo.

git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
cd gasm-devkit
just build
just gates

Workflow

1. Branch from development. Never commit directly to main, which is release-only.
2. Commit in Conventional Commits form: type(scope): description, subject line only, imperative mood, lowercase after the colon, no trailing full stop. Allowed types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert.
3. One logical change per commit. A refactor, a behaviour change and a formatting pass are three commits, never one.
4. Record every user-visible change in CHANGELOG.md under ## [development].
5. Add or update tests. Coverage stays at 80 percent or more; it is a hard gate.
6. Update the documentation when the public API, the configuration or the behaviour changes.
7. Open a pull request against development.

Releases are cut by merging development into main and tagging vX.Y.Z. The release workflow builds the assets and publishes the release and its notes.

Code style

gofmt and go vet run through just fmt and just vet, with zero diff and zero warnings tolerated. just vet is two gates, go vet ./... and go fix -diff ./..., so the modernisation rewrites are enforced too. just gates is the definition of done in one command, and the recipe file names what it contains. Errors are checked explicitly, wrapped as fmt.Errorf("context: %w", err), and nothing panics outside main. The recipe file holds the commands, and the language and standard-library surface is the one the go directive in go.mod pins.

• golang.org/x/arch is the one module dependency, and it is linked into the binary: gasm dis and the debugger's listings decode through it. Everything else is the standard library.
• No cgo and no C. The standalone encoder paths (gasm asm --format raw and --format elf) need no Go installation; gasm verify --ground-truth, gasm verify --fuzz, gasm audit-instructions and gasm asm --format goobj resolve through the installed Go toolchain.
• The parser, lexer and formatter are hand-written; the arch instruction tables are generated only by _gen/gen.go (just gen) and never edited by hand.
• Assembly committed to the repository goes through gasm fmt and gasm lint, so a .s file that gasm fmt -l . lists is unfinished.

New source files open with the project's two-line licence header, whose SPDX identifier matches LICENSE. Configuration files, workflows and dotfiles do not carry it.

AI contribution policy

AI tools are welcome as productivity aids and are a normal part of modern software development. What matters is that the contribution stays understandable, reviewable and genuinely useful.

• Disclose the assistance. If AI helped draft any part of a commit, issue, pull request or review, say so.

• Commit messages carry exactly one trailer, as a git trailer on the line after a blank line that closes the subject:

  Assisted-by: MODEL
  

  Name the model that did the work, spelled the way its maker spells it, for example GLM 5.3, DeepSeek V4.1 Flash or Qwen 3.8 Flash. No Co-Authored-By, no Signed-off-by, no other trailers, and no prose: the trailer is the disclosure.

• Issues and pull requests attribute the assistance in a comment, for example _Assisted-by: GLM 5.3_. It does not belong in the pull request description.

• Take responsibility. You are accountable for the accuracy, completeness and intent of everything you submit, whether or not AI produced it.

• Review before marking ready. Read the diff carefully, run it locally, and add the tests it needs. Do not mark a pull request ready until you can defend every change in it.

• Quality over quantity. Contributions that look like un-reviewed output, or whose author cannot engage substantively during review, may be closed.

• Preferred models. Prefer open-weight models with transparent training data and minimal output filtering.

AI assists. It does not replace judgement.

Continuous integration

Workflows live in .gitea/workflows/ and run on the project's own runners:

Workflow	Trigger	What it does
Test	push or pull request to development	build, format check, vet, modernisation, the test suite with the coverage floor, the CLI and debugger tests outside the profile, then the oracle-parity rerun against go tool asm
Release	a v* tag	the same gates as Test minus the oracle-parity step, then the matrix build, the version smoke test and the release itself; the race detector runs locally in just gates before the tag is cut

The local equivalent is just gates, which is the same set plus the race detector. The race detector also has its own workflow, dispatched by hand; it never runs on a push or a tag, where it would double the time and the memory a shared runner cannot spare.

Reporting bugs

Open an issue at https://sourcedock.dev/petrbalvin/gasm-devkit/issues with the version, the operating system and architecture, the exact command, the full output, and the expected against the actual behaviour.

Security issues do not go in the issue tracker. Report them as SECURITY.md describes, to opensource@petrbalvin.org.