108 lines
4.4 KiB
Markdown
108 lines
4.4 KiB
Markdown
# Contributing to gasm-devkit
|
|
|
|
Thanks for contributing to gasm-devkit.
|
|
|
|
## Development setup
|
|
|
|
Requirements: Go 1.27 or later, the [just](https://github.com/casey/just)
|
|
command runner, and a Linux host on amd64, arm64, riscv64 or loong64.
|
|
|
|
```sh
|
|
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](https://www.conventionalcommits.org/):
|
|
`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
|
|
|
|
```sh
|
|
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](https://sourcedock.dev/petrbalvin/gasm-devkit/issues)
|
|
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.
|