This page is for contributors. The goal is to help you set up the repo, make a focused change, validate it, and open a PR without guesswork.

Who this page is for

• Contributors preparing a local dev environment
• Maintainers validating changes before opening or reviewing a PR
• Doc or code authors checking the repo workflow and validation baseline

Read this next

• Open Architecture before touching unfamiliar subsystems
• Open Commands if your change affects CLI behavior or docs
• Open README if you need the broader English docs map

If you came from ...

• README: this page narrows the path to contributor-specific setup and validation
• Commands: come here when a CLI change also needs workflow, testing, or PR guidance
• AGENTS.md: use this page for the practical day-to-day contributor checklist

• Development and testing are pinned to Zig 0.16.0.
• Read AGENTS.md before code changes.
• Read CLAUDE.md if you need more project context, validation rules, or subsystem guidance.
• If you use the repository flake, both nix build and nix develop are pinned to Zig 0.16.0.

Check your Zig version first:

zig version

zig build
zig build -Doptimize=ReleaseSmall
zig build test --summary all

At minimum, run this before opening a PR for code changes:

zig build test --summary all

zig build -Dchannels=telegram,cli
zig build -Dengines=base,sqlite
zig build -Dtarget=x86_64-linux-musl
zig build -Dversion=2026.3.1

Notes:

• channels: limit which channel implementations are compiled in
• engines: limit memory engines in the build
• target: cross-compile target triple
• version: override the embedded version string (dev by default; release workflow injects the git tag)

1. Read the target module and nearby tests first.
2. Keep each PR focused on one concern.
3. Update docs and tests as part of the same change.
4. Validate before you open the PR.

If your change affects users, operators, or contributors, update the related docs in the same PR:

• Landing page: README.md
• English docs: docs/en/
• Chinese docs: docs/zh/
• Security policy: SECURITY.md
• Specialized deployment guide: SIGNAL.md
• Contribution guide: CONTRIBUTING.md

Documentation should stay:

• task-oriented
• copy-paste friendly
• consistent with src/main.zig and the current config schema
• synchronized across English and Chinese when both audiences are affected

Enable the repository hooks once per clone:

git config core.hooksPath .githooks

Hooks included:

• pre-commit runs zig fmt --check src/
• pre-push runs zig build test --summary all

Recommended:

git diff --check

Also verify links, paths, and command examples manually.

Required:

zig build test --summary all

Also run:

zig build -Doptimize=ReleaseSmall

Your PR description should explain:

1. what changed
2. why it changed
3. what validation you ran
4. any risks or follow-up work

Suggested template:

## Summary
- ...

## Validation
- zig build test --summary all

## Notes
- ...

• Architecture: docs/en/architecture.md
• Commands: docs/en/commands.md
• Contribution guide: CONTRIBUTING.md
• Engineering protocol: AGENTS.md

• Read Architecture before editing deeper runtime, security, or provider code
• Use Commands when your change touches the CLI surface or examples
• Open CONTRIBUTING.md before preparing the final PR description and review flow

• README
• Installation
• Configuration
• Commands