Development
Contributing to, building and understanding the Karkain compiler and
toolchain. Start here if you plan to modify .kark source, the Go
packages, or the compiler infrastructure.
Contribution Rules
These are the standing rules for work in this repository. They are not suggestions: every item below has been violated at least once in this project’s history, and the corresponding guard was added because of it.
Every commit is the repository owner’s work, and only the owner’s.
1. Attribution
One author, one identity: Ajit Kumar <ajitjava2@gmail.com>. Every commit’s author AND committer is the owner.
No co-author, assistant, or tool attribution is ever added to a commit message. This specifically includes
Co-Authored-By:,Signed-off-by:, andGenerated with/Generated bytrailers.Why this is a hard rule, not a preference. A
Co-Authored-Bytrailer causes that identity to appear in GitHub’s Insights → Contributors graph even though it authored nothing. On this repository that happened once: an assistant trailer put a bot on the contributor list, and because GitHub caches the contributors graph, the entry survived the history rewrite that removed it.Enforcement is mechanical, not a promise. A local
commit-msghook at.git/hooks/commit-msgstrips any such trailer before git records the commit. It always exits0: it removes the trailer, it never blocks a commit. The hook is deliberately local (.git/hooksis untracked), so this policy adds no files to the public repository.The owner is the only contributor. Third-party credit is granted only by the owner’s explicit decision, recorded in
AUTHORS— which currently lists one name and notes that entries are added “only with the contributor’s consent”.Tooling that can appear as a contributor is owner-side to remove. A bot identity on the repository comes from an installed GitHub App or an API token, never from the code. Revoking that access is an account action (Settings → Applications), which the repository cannot do for you.
2. Branch workflow
Work follows a fixed, dependency-free loop. There is no long-lived feature
branch and no version branch: main is shippable at all times.
develop ──work──▶ commit ──▶ merge into main ──▶ push
▲ │
└────────────────────── CI + Pages ───────────────────────┘
Branch from
develop.Commit work on
develop. One increment is one gate file, one audit note and one merge.Merge
developintomain(--no-ff, so the merge is recorded).Push both branches.
Never open a pull request for this loop, and never force-push main to
“fix” a red build. A force-push rewrites published history for every existing
clone; it is a last resort that must be agreed in advance.
3. Definition of done for a phase or increment
A unit of work is finished only when all of the following are true. Anything less is “green except X”, and X is not done.
[ ] The work is implemented and its gate exists as a test file.
- [ ] The gate is mutation-checked where it guards a comparison: forced to
fail, it must fail. A gate that cannot fail is not evidence.
[ ]
go build ./...is clean andgo vetpasses on the touched packages.- [ ] The gate passes and the regression gates it can break pass
(
pkg/native, the neighbouringphase*gates, and so on).
- [ ] The release build matrix still compiles for every shipped target
(see §4). A green test run on
linux/amd64does not prove the 32-bit and cross targets build.
- [ ] The audit note for the increment records the evidence,
including any defect found and fixed en route.
[ ]
AGENTS.mdcarries the completion record.[ ] Committed to
develop, merged intomain, both pushed.
4. Release build matrix (a hard gate)
Every Build (<goos>/<goarch>) job in ci.yml is a release gate, not
informational. The shipped archive set is:
linux/amd64 linux/386 linux/arm linux/arm64
linux/ppc64le linux/s390x windows/amd64 windows/arm64
darwin/amd64 darwin/arm64 freebsd/amd64 netbsd/amd64 openbsd/amd64
Verify the matrix locally before pushing when a change touches a package every binary links (a shared constant, an arch assumption, a syscall table):
for t in linux/386 linux/arm/7 linux/arm64; do
GOOS=${t%/*} GOARCH=${t#*/} CGO_ENABLED=0 go build -o /dev/null ./cmd/karkain
done
Warning
This gate is not theoretical. A 64-bit-only constant introduced during
increment 150 (MachoBase = 0x100000000) passed every local test on
windows/amd64 and broke linux/arm and linux/386 in CI, turning the
release red. A constant that does not fit in a 32-bit int must be declared
uint64 and used only through 64-bit arithmetic.
5. CI/CD and GitHub Pages
Both pipelines are mandatory and are part of the definition of done.
Pipeline |
Trigger |
What it must prove |
|---|---|---|
|
push to |
docs build, unit tests, the native PE execution job, the cross-linker matrix, and the full release build matrix |
|
push to |
|
Notes that are easy to get wrong:
Pages deploys from the CI artifact, not from committed HTML. The generated HTML is never committed; it is uploaded as a Pages artifact and published to the
github-pagesenvironment. Nothing indocs/build/is ever committed.Only a push to ``main`` deploys Pages. Pushing to
developruns CI but does not publish the site, so adevelop-only change leaves the public documentation on the older content until it is merged.The ``linkcheck`` job is informational (
continue-on-error: true), because external hosts flake. It should stay green as a matter of hygiene, but a red linkcheck never blocks the deploy.A red CI is a release blocker. Do not sign off a version checklist, and do not cut a tag, while a
BuildorTestjob is failing.The release job is tag-gated. The 13 archives and
checksums.txtare published only by thereleasejob, which runs when the ref is a tag. Cutting that tag is the owner’s decision alone.
6. Evidence discipline
A completion claim is only as strong as the check that produced it. A gate that can pass without comparing anything — for example one that skips when output is empty — is not evidence, and the wording that claims otherwise must be corrected rather than inherited.
A silent fallback is not a pass. If one engine quietly hands work to another, the result can be byte-identical while the intended code never ran. Every parity or pipeline gate must assert provenance (which component actually produced the output), not only the output itself.
Measure, do not assume. “This is too slow to cache” or “these two are equivalent” are claims that need a number. Where a decision rests on performance, the measurement belongs next to the decision, and the benchmark that produced it is committed so the claim can be re-checked.
A frozen increment stays frozen. A later defect does not reopen a completed increment; a corrective change names its owning layer, documents the demonstrated failure, re-pins anything whose bytes it moved, and runs the affected gates. New work found along the way becomes its own increment with its own baseline and gate.
7. What an increment is
An increment is one deliverable, one gate file, one audit note, one merge. It is planned by version but executed by increment, and a version ships only when every increment in its frozen scope is complete and every closure condition in its checklist holds.
Before an increment starts, its baseline note is written
(docs/audit/PHASE-<N>-BASELINE.md) recording the verified starting position,
the slices, the explicit non-goals, the risks, and the exit criteria. A baseline
written from assumptions rather than from the tree is worthless, so its claims
are verified by running the real thing.
See also
Compiler Internals — the compiler architecture in depth. Host Targets — where your host lives in the target model. Contributing — how to build, test, and propose a change. Testing — the test matrix and host constraints. Release Engineering — the release ceremony and the owner-only steps. Roadmap — where the project is going next.