Skip to content

how to contribute

Jump to bottom
Dom edited this page Jun 21, 2026 · 1 revision

How to contribute

Zipper is a single-maintainer project with an AI-assisted workflow. Contributions land through GitHub issues, branches named by issue type, and a strict PR gate that runs lint, unit tests, E2E, goldens, coverage, and robot reviews. This page is the entry point for the contribution section. It covers work pickup, the PR process, review expectations, and the definition of done. For the step-by-step branch-code-test-merge cycle, see Development workflow. For test specifics, see Testing. For tooling and linters, see Tooling. For conventions and style, see Patterns and conventions.

Picking up work

Work is tracked as GitHub issues. Issue priority, from highest to lowest, is: Blockers, Critical, High, Test Coverage, then Design/Refactor/KISS (only after relevant test coverage exists). Pick the highest-priority issue that is unassigned and not blocked.

Before coding, read the issue body and every comment. Comments are part of the spec. A design decision, implementation guide, or staleness note posted after the body supersedes the body. If the newest substantive comment contradicts the body, follow the comment and say so in the PR. If the issue is stale (the code it describes no longer exists, or another change already resolved it), do not implement it as written. Comment on the issue with evidence and a recommendation to close or retarget, then stop.

If README.md, Requirements.md, UBIQUITOUS_LANGUAGE.md, the issue body, and the implementation disagree, stop and identify the conflict before coding. Do not silently choose one source. The one exception is a newer issue comment superseding the issue body.

Branch and commit conventions

Branch from the latest main:

git checkout main && git pull
git checkout -b fix/ISSUE-NNN-short-desc

The prefix matches the issue type: fix/ for bugs, feat/ for features, refactor/, test/, docs/. Commit messages use Conventional Commits: fix:, feat:, refactor:, test:, docs:, chore:, deps:. Requirement IDs (REQ-XXX, FR-XXX) are immutable and must never be renumbered.

PR process

  1. Write a failing test first (TDD), then implement the fix.
  2. Run dotnet format --verify-no-changes src/ and dotnet test src/Zipper.Tests/Zipper.Tests.csproj after every change.
  3. Run autoreview before creating the PR. This is mandatory for any change touching logic, error handling, or public contracts. Docs-only, version-bump, and single-line fixes may use a self-review, noted as an exemption in the PR body.
  4. Commit and open the PR. The PR body must include a ## Release Notes section per the Release Notes Mandate. One PR equals one release.
  5. Monitor CI until every check passes. Reproduce each gate locally first using the docs/cicd.md gate-to-command table so you fail fast instead of waiting on CI minutes.
  6. Check SonarCloud on the PR after CI completes. Fix all BLOCKER and MAJOR issues before merge. The quality gate can also fail on new-code conditions (duplication, coverage) with zero BLOCKER/MAJOR issues, so query the gate conditions, not just the issue list.
  7. Run bash tests/wait-for-reviews.sh <PR-number> after creating the PR and again after every push. The script blocks until every robot reviewer (Gemini Code Assist, CodeRabbit, Codex) has reviewed or declared a rate-limit skip, then exits non-zero while any review thread is unresolved. A "pass" or "skipped" check status from a review bot is not an approval. Only the script exiting 0 is.
  8. Merge after all checks pass, wait-for-reviews.sh exits 0, and reviews are addressed. Branch protection on main enforces this server-side: GitHub refuses the merge while any review thread is unresolved.

Review expectations

For each finding a robot reviewer reports, verify it against the current code. Fix it if still valid, or reply on the thread with a brief skip reason (for example, "conflicts with an explicit design decision"), then resolve the thread and re-run wait-for-reviews.sh. Blocking and major issues must be fixed. Nitpicks may be skipped with a reason but never silently ignored.

A review-driven fix that changes behavior can stale the architecture diagram, ADRs, glossary, or code comments. Re-verify those before pushing the fix. See Critical Rules 1, 4, and 5 in AGENTS.md.

After a force-push, bot comments may reference code that no longer exists. Verify comments still apply before acting on them. Skip already-addressed comments, but reply acknowledging them.

Definition of done

A change is done when all of the following hold:

  • Unit tests pass: dotnet test src/Zipper.Tests/Zipper.Tests.csproj.
  • Lint is clean: dotnet format --verify-no-changes src/.
  • E2E suite passes: dotnet build -c Release && ./tests/run-tests.sh (or tests\run-tests.bat on Windows).
  • Analyzer tests pass when touching src/Zipper.Analyzers/: dotnet test src/Zipper.Analyzers.Tests/Zipper.Analyzers.Tests.csproj.
  • CI is green on all three operating systems.
  • tests/wait-for-reviews.sh exits 0.
  • SonarCloud has zero BLOCKER and MAJOR issues on new code.
  • Test coverage did not decrease in substance. Every removed or modified test was replaced with a test covering the same or a stricter behavioral contract.
  • If the change touched CLI behavior, Load File/Audit File/Production Set formats, or Email domain names, all four docs were updated: README.md, Requirements.md, UBIQUITOUS_LANGUAGE.md, and the E2E scripts (both .sh and .bat).
  • If the change deviates from docs/architecture.md diagrams or makes one stale, it has explicit human approval and a same-PR diagram update.

Key source files

File Purpose
AGENTS.md Agent workflow, commands, critical rules, per-issue workflow
CI.md SonarCloud, CodeRabbit, CodeQL, goldens, dependency policy
docs/cicd.md Pipeline map, gates summary, quick reference for agents
.github/pull_request_template.md PR body template with Release Notes section
tests/wait-for-reviews.sh Robot-review gate script

Related pages

Zipper overview

By the numbers

Lore

How to contribute

Systems

Features

Primitives

Background

Reference

Maintainers

Clone this wiki locally