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. .. toctree:: :maxdepth: 2 contributing testing architecture roadmap feature-freeze semver-policy release reporting-bugs developer-preview .. _contribution-rules: =================== 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.** .. _attribution: 1. Attribution ============== * **One author, one identity: Ajit Kumar .** 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. .. _branch-workflow: 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. .. code-block:: text 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. .. _definition-of-done: 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. .. _release-matrix: 4. Release build matrix (a hard gate) ====================================== Every ``Build (/)`` job in ``ci.yml`` is a **release gate**, not informational. The shipped archive set is: .. code-block:: text 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): .. code-block:: bash 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. .. _ci-and-docs: 5. CI/CD and GitHub Pages ========================= Both pipelines are **mandatory** and are part of the definition of done. .. list-table:: :header-rows: 1 :widths: 22 20 58 * - 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. .. _evidence-discipline: 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. .. _increment-definition: 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--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. .. seealso:: :doc:`/compiler/index` — the compiler architecture in depth. :doc:`/targets/host-targets` — where your host lives in the target model. :doc:`/development/contributing` — how to build, test, and propose a change. :doc:`/development/testing` — the test matrix and host constraints. :doc:`/development/release` — the release ceremony and the owner-only steps. :doc:`/development/roadmap` — where the project is going next.