docs: add the full documentation surface — AGENTS, CONTRIBUTING, cli and development references

Assisted-by: DeepSeek V4 Flash
2026-08-01 05:22:00 +02:00
parent 89d633f4bb
commit c77d68018c
7 changed files with 1519 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Contributing to gasm-devkit
+
+## Prerequisites
+
+- Go 1.26 or later (`toolchain go1.26.5`)
+- `just` command runner
+- A Linux, FreeBSD, or macOS host on amd64 or arm64
+
+## 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
+
+There is no CI pipeline in this repository. The Definition of Done
+(`just build` + `just test` + `just fmt`) is enforced locally.
+
+## 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: DeepSeek V4 Pro_
+```
+
+## Questions
+
+Open an issue at
+[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues).