102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
# 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).
|