Repository rules for work on the V compiler, standard library, and tools. See
CONTRIBUTING.md for architecture and contribution details,
TESTS.md for test infrastructure, and doc/docs.md for language reference.
The local ./v workflow and test requirements below take precedence over examples in those docs.
- Change only what the request requires. Keep refactors small and within files already being edited.
- Preserve and report unrelated work; do not modify or stash it without explicit instruction.
- Ask before large refactors, changes spanning multiple root directories, or large changes to parser rules, resolution, codegen, diagnostics, or CLI behavior. Docs-only edits across directories need no approval. Ask if the scope is unclear.
- Ask before editing
ci/,Dockerfile*, orthirdparty/unless explicitly requested. For CI, clarify whether local validation or CI-only coverage is expected. - Reading, building, targeted testing, and formatting need no approval. Ask before
./v test-all; broad refactors require that suite. - Never change tests to hide failures. Update
.outexpectations only for intended behavior changes and explain why. Treat.vvfiles as fixtures; avoid formatting them unless changing their behavior and expectations. - Update relevant README, module docs,
doc/, ortutorials/for public API or behavior changes, including compiler flags, diagnostics, CLI output, and output ordering. Internal refactors need no doc changes. Ask if unsure whether behavior is public. - Edit
CHANGELOG.mdandROADMAP.mdonly when explicitly requested.
- Work from the repo root. Check
git statusand whether./vexists before starting. - Use
./vfor builds, runs, tests, and tools. Put compiler flags before the subcommand or file:./v -g run file.v. Flags after a subcommand are passed to that subcommand. - If
./vis missing, runmake(makev.baton Windows). Requires Git, make, and clang or gcc. - Rebuild in place with
./v selfafter changes tovlib/v/,cmd/v/, or core modules (builtin,strings,os,strconv,time), before testing. Rebuild if unsure whether./vis current. Overwriting it is intentional. - Format touched and new
.v/.vshfiles with./v fmt -w file.v. Check touched Markdown with./v check-md file.mdbefore committing; keep lines at most 100 characters. Preserve existing formatting in other files.
If the compiler becomes unusable, check git status before recovery. Only stash for recovery when
the compiler is bricked or the user authorizes it; the recovery sequence is git stash, make,
git stash apply. Keep unrelated work safe.
Start with the smallest relevant tests and run all applicable checks. For compiler changes in
vlib/v/ or cmd/v/, run both:
./v -silent vlib/v/compiler_errors_test.v
./v -silent test vlib/v/Additional checks by scope:
| Change | Check |
|---|---|
| Docs only | ./v check-md file.md; no rebuild or other tests unless they read those docs |
| Core or other standard library module | Nearest *_test.v or ./v -silent test vlib/path/ |
| Parser | ./v -silent test vlib/v/parser/ |
| Checker | ./v -silent test vlib/v/types/ |
Comptime in types/ or transform/ |
./v -silent test vlib/v/tests/ and comptime tests |
| Diagnostics, error reporting, output | ./v -silent vlib/v/slow_tests/inout/compiler_test.v |
| C code generation | ./v -silent test vlib/v/gen/c/ |
| REPL | ./v -silent vlib/v/slow_tests/repl/repl_test.v |
Tools in cmd/tools/ |
Tool tests, or the smallest test exercising the tool |
- For vfmt, run
cmd/tools/vfmt_test.vandvlib/v/gen/v/gen_test.v; for vdoc, runcmd/tools/vdoc/vdoc_test.vwith./v. - For JS/native/WASM changes, use focused tests with
./v -b js|native|wasm ...; avoid broad backend test runs. Consider./v -cstrict -cc clang -silent test vlib/v/for C codegen changes. - Add regression tests for option/result changes in
vlib/v/tests/and for new public APIs. - Run
./v -silent test-fmtonly when asked or validating the whole tree. Run./v vet vlib/vonly when asked or changing more than three checker files invlib/v/types/. - Ask if test selection is unclear. When time-constrained, prioritize compiler error tests and
focused regressions; report skipped coverage. Docs-only work still requires
check-md. - Output tests match exactly, including whitespace (
.vv+.out, or.run.out). UseVAUTOFIX=1only for intended output changes; run the affected test twice when updating outputs. VTEST_ONLY=glob_patternfilters tests;VTEST_HIDE_OK=1hides successful results.
- Add doc comments immediately before new or modified public functions and methods, starting with
the function name:
// the_name does .... Keep other comments concise; preserve correct comments. - Keep
unsafeblocks limited to necessary low-level operations, with a comment explaining why. Do not wrap ordinary V logic inunsafe. - Avoid hidden or bidirectional Unicode in source and Markdown.
- Module names match the directory name; imports follow the directory hierarchy (
import abc.def). - Prefer platform/backend file suffixes when an entire file is specific to one environment:
.c.v,.js.v,.native.v,.wasm.v,_windows.c.v,_linux.c.v,_nix.c.v,_default.c.v. Custom flags use_d_flag.vor_notd_flag.v. Do not combine flag and OS suffixes; use$ifinside the flag-specific file.
- The V compiler must never parse, scan, expand, or infer declarations from C headers, including bundled headers. Leave preprocessing and include cycles to the C toolchain.
- Track native dependencies through compiler-produced manifests or opaque cache inputs. Bypass reuse when the manifest cannot establish safety. Header inspection must not be reintroduced for caches, native bridges, backend selection, or portable C output.
- Put
C.andJS.uses in.c.vand.js.vfiles.-Wimpure-vdetects accidental impurity. Leave existing interop alone unless needed for the task; prefer moving touched interop to the appropriate file. Use correctconst_prefixes in C function redeclarations.
- Use
$iffor platform/compiler conditions; runtimeifcannot exclude unavailable symbols. Custom defines require the question mark:$if myflag ? { ... }with-d myflag. - Reflection uses
$forover type metadata and is unrolled at compile time. Use$iffor metadata type checks. Reflected method calls belong inside a compile-time method iteration. $embed_filereturnsEmbedFileData; use.to_string()or.to_bytes().$envreads at compile time;os.getenvreads at runtime.- Prefer unprefixed
typeof,sizeof,isreftype,__offsetof, anddumpover their aliases. ?Typeis optional;!Typeis a result. Check option handling in guards, struct initialization, ternaries, SQL, and fixed arrays when changing related codegen.- If a tool behaves unexpectedly, check whether it shells out to system
vinstead of./v.
- Keep generated C with
./v -keepc -cg run file.v; use-gfor V lines,-showccfor the C command, and-show-c-outputfor C diagnostics. Use-printfn main__main -o file.cto isolate a function. - Compiler tracing uses
-d trace_scanner,trace_parser,trace_checker, ortrace_gen; stage timing uses-d time_parsingortime_checking. Remove temporary debug tags before committing. VFLAGSandVEXEcan override invocations;TMPDIRcontrols temporary C output.SOURCE_DATE_EPOCHfixes build timestamps for reproducibility.- Every compiler fix must preserve or improve efficiency. Read vself_speed.md before compiler work. Follow its fixed-fixture benchmark protocol; investigate instruction-count regressions before merging.
- Compare retired instructions and instructions per parsed source line, retaining elapsed time, cycles, and peak memory. Use matched production compilers, verify generated C, and preserve logs. Require one warmup per role and ten alternating measured pairs with positive hardware counters. An idle host is unnecessary for instruction counts; latency claims need controlled measurements.
- Compiler entry:
cmd/v/v.v; pipeline:v.driverorchestratesscanner->parser/flat->types->transform->markused->gen/c, undervlib/v/. - Other backends:
vlib/v/gen/fastc/,gen/arm64/, andgen/wasm/, with SSA/MIR lowerings. - Diagnostics: token spans in
v.token.Pos, type checking inv.types.TypeChecker, formatting invlib/v/errors/. - Compiler feature tests:
vlib/v/tests/; output and slow tests:vlib/v/slow_tests/. - Standard library:
vlib/; tools:cmd/tools/; examples:examples/.
- Keep commits focused on one logical change; follow CONTRIBUTING.md.
- Ask before force-pushing or dropping hunks. If branch divergence requires a rebase or merge, explain the conflict and ask when the strategy is ambiguous; prefer rebase for linear history.
- Confirm touched files with
git statusbefore reporting. Be concise and include behavior changes (or none), tests run and skipped with reasons, touched paths, doc updates, and unrelated changes. Explain.outupdates. If blocked, state what was attempted, why it failed, and what remains.