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:, and Generated with/Generated by trailers.

  • Why this is a hard rule, not a preference. A Co-Authored-By trailer 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-msg hook at .git/hooks/commit-msg strips any such trailer before git records the commit. It always exits 0: it removes the trailer, it never blocks a commit. The hook is deliberately local (.git/hooks is 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 ───────────────────────┘
  1. Branch from develop.

  2. Commit work on develop. One increment is one gate file, one audit note and one merge.

  3. Merge develop into main (--no-ff, so the merge is recorded).

  4. 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 and go vet passes on the touched packages.

  • [ ] The gate passes and the regression gates it can break pass

    (pkg/native, the neighbouring phase* gates, and so on).

  • [ ] The release build matrix still compiles for every shipped target

    (see §4). A green test run on linux/amd64 does 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.md carries the completion record.

  • [ ] Committed to develop, merged into main, 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

CI/CD (ci.yml)

push to main or develop, on v* tags, and manual

docs build, unit tests, the native PE execution job, the cross-linker matrix, and the full release build matrix

Documentation (docs.yml)

push to main, and manual

sphinx -b html -W, the required-page check, then deploy to GitHub Pages

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-pages environment. Nothing in docs/build/ is ever committed.

  • Only a push to ``main`` deploys Pages. Pushing to develop runs CI but does not publish the site, so a develop-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 Build or Test job is failing.

  • The release job is tag-gated. The 13 archives and checksums.txt are published only by the release job, 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.