contributing

Pre-Alpha. This page describes behavior that may change.

Contributions to Ze are welcome. The process is structured because the project is structured: Ze is built from specs, and the same specs that drive the maintainer's work drive contributions. If you have written code for an open-source project before, the workflow will look familiar; the part that may be new is that you wait for a spec before writing the code.

The five steps

1. Open an issue. Describe what you want to work on. Explain the problem you are solving, not just the change you want to make.
2. Wait for a spec. The maintainer creates a spec from plan/TEMPLATE.md. The spec is what defines the work. It is the source of truth for what "done" means and what the acceptance criteria are. Do not start coding before the spec exists.
3. Implement the spec. Follow the rules in ai/rules/ in the repo. Those rules apply to every contribution, whether you write the code by hand or with AI assistance.
4. Run /ze-review-deep before submitting. The maintainer reviews contributions with Claude Code. Submitting code that has already been through the deep review path makes that smooth. The Claude Code cheat sheet lists every project-specific command.
5. Sign your commits. git commit -s certifies that you accept the terms of the CLA.

The ground rules

The rules live in ai/rules/, one file per topic, and they are shared by every agent and every contributor rather than being tied to one tool. Two generated files sit beside them: ai/rules/TRIGGERS.md names every rule with the situation that makes it apply, and ai/rules/CORE.md carries in full the rules that apply before the shape of a task is known. .claude/rules/ keeps only the Claude Code session mechanics.

A few of those rules shape every contribution and are worth knowing about up front.

• TDD. Tests are written before the implementation. The test exists, fails for the right reason, then the implementation makes it pass.
• Specs drive the work. No code without a spec. This is not bureaucracy, it is the only way the project stays coherent under heavy AI-assisted development.
• make ze-precommit-verify must pass before submission. That target runs the lint, the unit suite, the functional suite, and the ExaBGP suite. If any of them fail, the patch is not ready.
• No partial deliveries. Code, tests, and documentation land in one piece. A change without tests is not a change. A change without documentation is not a change.

Licence and the CLA

Ze is licensed under the GNU Affero General Public License v3.0. The CLA grants the maintainer the right to offer the project under additional terms (dual licensing). Your contributions remain available under AGPL-3.0 to the public at all times. The two are not in tension: the CLA exists so the project can offer commercial licensing later without orphaning the open-source release.

What "good" looks like

The maintainer reviews patches through Claude Code's /ze-review-deep workflow. That review checks the patch against the spec, against the repo's coding standards, against the test plan, and against the documentation requirement. If you run that workflow yourself before sending the patch, you find the same problems the maintainer would find, only an hour earlier.

The other tool that pays for itself is make ze-precommit-verify-changed, which runs the full verification only on packages your branch has touched. It is fast enough to run on every save once you get into the rhythm.

Where the rules live

• ai/rules/ in the repo for the coding, testing, and workflow rules, with INDEX.md as the dispatch.
• ai/patterns/ for the "how to add a thing" templates: CLI command, config option, plugin, web endpoint, BGP family, functional test.
• docs/claude-code-cheatsheet.md for the project's slash commands.
• CONTRIBUTING.md for the canonical version of this page.

Where to start

If you have not picked an issue yet, the project tracker is the place to look. Smaller issues in the operator surfaces (CLI commands, ze show enhancements, plugin polish) are usually easier to land than core engine changes. If you are making your first contribution to Ze, picking one of those is a faster way to see the workflow end to end than starting with something deep in the BGP stack.

See also

• Building for how to get a working binary first.
• Plugin development if your contribution is a plugin rather than a core change.
• In-tree CONTRIBUTING.md and ai/rules/ for the canonical rules.

Adapted from main/CONTRIBUTING.md.