Contributing

Contributing

This page tells you how the project accepts changes. The repository file CONTRIBUTING.md has the same rules.

Applies to: the repository and this wiki.

Rules for commits

• Every commit is GPG-signed by the maintainer, Christian Presley¹.
• The maintainer is the only author and the only committer.
• Commit messages have no attribution trailer. The commit-msg hook rejects them.
• The subject follows Conventional Commits: type(scope): description. The types are feat, fix, docs, style, refactor, perf, test, build, ci, chore and revert.
• The body has one line for each changed file: path: what changed. The hook and the commit-policy CI job check this. The CI job also checks the author and the committer.
• Merges happen on the maintainer's computer with git merge --ff-only. The GitHub web interface is not used for merges².
• Pull request descriptions do not carry a generator or attribution line.

If you send a pull request, the maintainer applies your change as a signed commit and credits you in CHANGELOG.md.

Steps: set up the repository

1. Install Zig 0.16.0.
2. Clone the repository.
3. Run git config core.hooksPath .githooks.
4. Run zig build test.

Steps: before you send a change

1. Run zig build fmt.
2. Run zig build test.
3. Run zig build lint-docs when you changed prose.
4. Run zig build census when you changed the protocol types.
5. Run zig build gen-bibliography when you changed the bibliography.
6. Run zig build gen-dictionary when you changed a word list in docs/dictionary/.
7. Run zig build spec-matrix when you changed docs/spec/requirement_tests.zon or a test that it names.

Prose

All prose uses the project profile of ASD-STE100 Simplified Technical English. See the Style Guide and the Dictionary.

The wiki

Edit the wiki only in a clone of the wiki repository. Commit with the same rules as the main repository. Do not use the web editor. Every page cites its sources in a References section that points to the Bibliography.

Before you commit a page, run zig build lint-docs -- --strict --wiki-dir ../zig-sdk.wiki in the main repository. The linter also checks the links between the pages and the page template. The job wiki-lint of the nightly workflow runs the same check. It also compares the pages Bibliography and Dictionary with the generated pages.

Scope

The SDK obeys MCP specification revision 2026-07-28 only. The project does not accept changes that add behavior from older revisions.

References

1. GH-SIGNED-COMMITS: About commit signature verification.
2. GH-COAUTHORS: Why web merges add a second committer.