Reporting Bugs
A good bug report lets a maintainer reproduce your problem without guessing
about your machine, your version, or your command. This page is the
canonical workflow for reporting a Karkain compiler or toolchain problem.
The GitHub issue templates (.github/ISSUE_TEMPLATE/) use exactly these
fields.
Before you file
Find the smallest command that reproduces the problem. Two lines of
.karkare better than two hundred.Run it on the current build of the toolchain:
karkain run <file>withKARKAIN_ENGINE` unset (the default ``kccengine) and, if relevant, again withKARKAIN_ENGINE=go.Reproduce twice. If the result is nondeterministic, say so explicitly.
If you reproduce a security vulnerability, do not open a public issue —
see SECURITY.md.
Collect the diagnostic information
Every report needs the following. None of these require private data.
Field |
How to gather it |
|---|---|
Karkain version |
|
OS |
e.g. |
Architecture |
|
Engine |
The |
Command |
The exact |
Source file |
The minimal, self-contained |
Expected result |
What you expected to happen. |
Actual result |
What happened instead: output, |
Do not include private information: no credentials, no tokens, no personal paths beyond what is needed to reproduce, no unrelated project code.
The reproduction script
For engine-parity or diagnostic bugs, attach (or paste) the two-line script that shows the divergence:
# shell / PowerShell
karkain check repro.kark
karkain run repro.kark
KARKAIN_ENGINE=go karkain run repro.kark
echo Exit: $LASTEXITCODE # or $?
For a panic or crash, add steps 1-3 from the compilation pipeline
(go build ./cmd/karkain + the failing command) so the build identity is
reproducible.
Filing the issue
Open the issue at https://github.com/ajit-ai/Karkain/issues/new/choose and pick Bug Report. The template collects the fields above in order. If you are unsure whether the behavior is a bug or intended, open a Documentation Issue or ask first — maintainers prefer a question over a mislabeled bug.
After you file
Add a comment if you discover the minimal reproduction case afterwards, or if behavior changes between two builds.
If a maintainer asks for clarification, treat the issue as blocked until you answer; stale questions prolong the fix.
Bugs filed against the current Beta line are fixed in the next Beta/RC patch and noted in Release Notes.
See also
Status — the status vocabulary (what counts as a bug vs. a planned feature). Diagnostics — the error-code contract. Beta 1 — what the Beta stable core claims. Installation — how to get the exact build you are testing.