Contributing
Welcome to the Karkain contributor guide. This page is the minimum needed to produce a correct, mergeable pull request.
Fork, branch, commit, PR
Fork the repository on GitHub.
Create a branch off
develop— descriptive names preferred, e.g.feature/phase-114-examples.Write code in
.karkfiles, Go packages, or documentation (RST underdocs/source/).Commit — one logical change per commit; the commit message should describe what changed and why, not how.
Open a PR against
develop. The PR description should state the feature boundary, what was tested, and any honest limitations.
Branch workflow (hard rule)
After every Phase completion and successful test run:
Commit all changes to
develop.Merge
developintomain.Push both branches to origin.
This ensures main always reflects the latest working state. This is a
hard rule — never skip this step.
Running the test suite
Run the full test suite before committing. All tests must pass.
go test ./pkg/lexer/... ./pkg/parser/... ./pkg/codegen/... ./pkg/pm/... -count=1
On the documented 4 GB host, run single-package tests sequentially:
GOMAXPROCS=1 GOGC=60 go test ./pkg/lexer/... -count=1
GOMAXPROCS=1 GOGC=60 go test ./pkg/parser/... -count=1
Note
The CLI test suite (go test ./pkg/cli/...) is large; run it in a
dedicated session rather than as part of a fast commit cycle.
Code style
No comments in source unless explicitly asked for them.
Use the
.karkextension for all Karkain source files.Follow existing patterns — check
pkg/package style, the conformance convention, and the example structure before inventing new ones.The language is authored in Karkain itself (
src/compiler/*.kark) and in Go (pkg/**/); follow whichever applies to your change.
Self-hosting boundary
Changes to src/compiler/*.kark are part of the self-hosted compiler.
Modify them with care: the Go codegen path and the self-hosted kcc
engine must agree. Test with both engines explicitly:
KARKAIN_ENGINE=go go test ./pkg/cli/... -run TestPhase99_Selfhosted -count=1
KARKAIN_ENGINE=kcc go test ./pkg/cli/... -run TestPhase99_Selfhosted -count=1
Language surface changes
New keywords, builtins or runtime helpers need changes in multiple places at once — a minimal parity map:
Lexer:
pkg/lexer/lexer.go(token type) andsrc/compiler/lexer.kark(self-hosted mirror).Parser:
pkg/parser/parser.goandsrc/compiler/parser.kark.Semantic:
pkg/sema/resolve.goandsrc/compiler/checker.kark.Codegen:
pkg/codegen/codegen.goandsrc/compiler/codegen.kark.
All additions must pass the full regression suite on both engines before committing.
Security rules
Never commit secrets, keys or credentials.
Never log or expose secrets in generated code.
Follow the security rules in the repository root
AGENTS.md.
See also
Testing — how the test suite is structured and how to run it. Architecture — repository layout and package map.