For Contributors

For Contributors

I prefer changes that start from observable behavior and then trace inward to the implementation. z-fasta shares contracts across commands, so a small parser change can reach farther than one source file.

Build and test

Install Zig 0.16.0 from the official Zig download page and confirm the compiler before building:

zig version
zig build
zig build test --summary all
zig build test -Doptimize=ReleaseFast --summary all
zig build -Doptimize=ReleaseFast

The version command must print 0.16.0. A compiler installed on your PATH is fine when it is that exact version. The repository does not provide a public Zig wrapper or compiler download.

Tests select the executable compiled for their build mode and run with copied fixtures and generated indexes in the build cache. They do not install into zig-out or write sidecars beside source fixtures. Run zig build -Doptimize=ReleaseFast before installed smoke checks, the shell consumer, or local verification scripts.

For a focused edit, select the owning suite and optionally filter test names:

zig build test-index
zig build test-get
zig build test-stats
zig build test-validate
zig build test-cli -Dtest-filter=dispatch

The filter applies to Zig tests. Separate native callers still run when selected through test-diagnostics or test. Finish code topics with both full test modes.

Source map

• src/main.zig: CLI parsing, help, dispatch, diagnostics and checked final status.
• src/root.zig: the Zig package: IndexedReader, RecordReader, and validation; Zig package describes it.
• src/diagnostics.zig: native codes, observed facts and caller-owned failure storage.
• src/reporting.zig: text and JSON encoding without allocation or flushing.
• src/indexer.zig: record scanning and index output.
• src/index_format.zig: .zfi or .fai loading, validation, lookup, and ownership.
• src/getter.zig: requests, coordinates, transforms, and bounded output.
• src/stats.zig: length and composition reports.
• src/validator.zig: the streaming validation scan, its report, and the repair written in the same pass.
• src/bed_parser.zig: BED row conversion and strand parsing.
• src/fasta.zig: bases, identifier ends, alphabet detection, the IUPAC complement, the record scanner, and the record reader.
• src/platform.zig: portable read-only mapping and advice.

The Wiki owns public behavior and workflow documentation. Source files and their tests own implementation details that are not part of the public contract.

Native diagnostic checks

zig build test-diagnostics
zig build test-reporting
bash tests/consumer_json.sh

The separate caller in tests/consumer_commands.zig handles failures from the actual command functions and then calls them again successfully. It uses existing exports without running the CLI dispatcher. Preserve finite error unions, allocator cleanup, original causes and the primary failure when cleanup or reporting also fails. Reset Failure once at the owning operation entry; nested helpers retain facts before returning and must not reset them.

Borrowed source labels live through handling or reset. Retained preview views belong to their Failure. A validator Report copies the identifiers it keeps. Failure capture allocates no new message; preview exhaustion marks truncation and must not hide the original failure. See Error diagnostics for units, encoding and output states.

Local correctness gates

bash bench/index/run.sh --skip-benchmarks --skip-messy --skip-report
bash bench/get/run.sh --skip-benchmarks --skip-messy --skip-report
bash bench/stats/run.sh --skip-benchmarks --skip-messy --skip-report
bash bench/validate/run.sh --skip-benchmarks --skip-report

Run every affected gate after code changes. Synthetic unit fixtures do not replace real-data and peer verification.

Contracts to preserve

• A present .zfi is authoritative.
• Positional GET stays byte-compatible with samtools on the verified path.
• .fai emission fails instead of describing non-uniform layout incorrectly.
• .zfi wire bytes remain versioned and backward-aware.
• Duplicate lookup is first exact match.
• Positional and BED coordinate systems remain distinct and explicit.
• Shared type detection changes are checked in stats, GET, and validate.
• GET and index hot paths stay bounded by fixed sequence payload buffers.
• Validate fix preserves every header byte and every symbol, and never overwrites input.

Documentation update map

When CLI behavior changes, update:

• the relevant command page;
• Command cheat sheet;
• affected Recipes;
• Troubleshooting when diagnostics or recovery change;
• FAQ when the user decision changes;
• Limits and supported formats when a boundary moves;
• _Sidebar.md when pages or command names change;
• the repository README.md for landing-page claims.

When format behavior changes, also update Index formats and the internal .zfi wire contract.

The authored Wiki pages live in wiki/ in the main repository. Edit and review that directory first. Pull requests validate the tracked source. Pushes to main validate and publish it to the GitHub Wiki automatically. A manual workflow dispatch can also publish the selected main branch after validation. Do not leave a correction only in the live Wiki.

Important

Examples are product claims. Verify command, status, stdout, stderr, and filesystem effects before publishing them.

Writing rules

• Use short direct sentences and active voice.
• Keep prose unwrapped in Markdown source.
• Use fenced code blocks with language tags.
• Use tables only when comparison or repeated numeric structure earns one.
• Use no more than one or two GitHub alerts per page.
• Use alerts for user decisions, not decoration.
• Use <details> for secondary output or advanced explanations.
• Avoid emojis, decorative Unicode, and em-dashes.
• Link to one owner instead of duplicating deep format or implementation detail.

Test documentation links

Before publishing Wiki changes:

1. Check every sidebar page exists.
2. Check every internal page link uses the published filename.
3. Preview alerts and collapsed sections on GitHub.
4. Run representative commands for changed examples.
5. Confirm the documented version.
6. Search for removed flags and stale limits.

Report a code change honestly

State what succeeded, what failed or was redone, what was skipped, and whether the work is complete. Include the exact gates run.