--- name: solnix-contributor description: > Contribute to Solnix: send a patch by email to hackers@solnix.io (a recipe change, a new package or a version bump, a module, a fix to these skills), follow the email-patch governance (+1/0/-1 votes, OWNERS, timers, quorums), report a bug or a security issue the right way, write handbook documentation. Says which team owns what (the build team: the Solnix OS repo; the infra team: solnix.io, the cache, its signing and the queue). Use when preparing a patch, a cover letter, a bug or security report, or a handbook chapter. For upstream illumos or nixpkgs see steering/upstream-ai-policies.md; for changing illumos-gate itself, solnix-illumos-dev. license: CC0-1.0 metadata: author: solnix version: "0.2.0" persona: contributor --- # Solnix: contributor Solnix takes changes as email patches on `hackers@solnix.io`; embargoed security work goes to `security@solnix.io` ([asset-lifecycle-governance-v2.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/design/asset-lifecycle-governance-v2.md), §1 Lists). An agent prepares the patch and the mail; the human sends it. Read `steering/email-patch-governance.md` and `steering/voice.md` (repo root). ## Tools this uses `search_packages`, `package_status`, `search_handbook`, `get_handbook` (this server); `git format-patch`, `git`, `nix build` (standard commands). ## Who owns what | area | owner | source | |---|---|---| | the Solnix OS repo (`codeberg.org/solnix/solnix`, mirrored to `git.solnix.io/solnix.git`): modules, `pkgs/illumos/`, `.kiro/steering/`, `docs/registry/recipes.tsv` (the source of truth) | build team | [AGENTS.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/AGENTS.md); [builder-queue.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/builder-queue.md), The contract; [handoff: 20261015-edition-branches-26.11-unstable.md](https://codeberg.org/solnix/solnix-infra/src/commit/807157bf3453500cc1b383643513239455e27ca7/docs/handoff/20261015-edition-branches-26.11-unstable.md), Where we are | | package production, the builder script | build team | [handoff: builder-steering-queue-and-work.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/builder-steering-queue-and-work.md) | | the site, cache.solnix.io, search.solnix.io, the submit pipeline and staging | infra team | AGENTS.md, "solnix.io belongs to the infra team" | | reviewing and serving the served copy of recipes.tsv; signing with the 8UNr key; the work queue | infra team | builder-queue.md, The contract and The queue | | package metadata index (pg_mentat) | infra team | [nix-conventions.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/nix-conventions.md), Package metadata index | | the site and handbook (`codeberg.org/solnix/solnix-site`); infra and services (`solnix-infra`) | infra team | AGENTS.md, "solnix.io belongs to the infra team"; builder-steering-queue-and-work.md ("the solnix.io infra repo"); [Handbook: Contributing](https://solnix.io/docs/handbook/contributing#repos), Repos | The build team does not edit the infra team's repos or use its credentials. When something there is wrong, the build team writes a report and the maintainer routes it (AGENTS.md). ## What the governance design means for your patch The design is marked "design / in-progress (2026-10-11)". Its §10 names, as new components the process needs, the eval-CI bot, the bridge that parses the email commands below, the OWNERS approval checker and the timer driver. What it decides: - **Votes** are `+1`, `0` or `-1` on one patch version; anyone may vote. A `-1` from an owner of a region the diff touches blocks it until withdrawn or overruled (design §5.1, §8.5). An available owner's silence also holds it. - **Owners** come from an `OWNERS` file per repo, longest path prefix wins (§2). A leaf package needs one owner's approval; the gate/toolchain, the trust path, `security/**` and `OWNERS` need an owner quorum (§5.5). - **Reproduction.** A change to a built artifact also needs a reproducibility quorum: independent builders produce the same hash, and tests pass (§3, §8.1). The owner's commit approval comes after that, and names the hash (§5.4). - **Timers.** Each governance timer defaults to 3 business days; a committer changes one on the thread with `adjust-timeout: +1w` or `5b` (§6, §8.2). An expired timer nags, advances or expires the thread, as §6 sets for each state (an idle review: a nag, then withdrawn after twice the timer). - **A new version** is a new `[PATCH vN]` mail; it resets review for that version (§4). - **Commands** such as `adjust-timeout:` bind only from a committer, in mail signed with a registered key, in a block at the bottom of the body; votes count without a signature (§9). ## Send a patch 1. **Clone the source.** `git clone https://git.solnix.io/solnix.git`. Done when `git log -1` works in the clone. 2. **Work on `unstable`**, the development branch (`steering/edition-policy.md`; [handoff: from-builder-20261018T143000-ami-verified-repoint-and-branches-done.md](https://codeberg.org/solnix/solnix-infra/src/commit/807157bf3453500cc1b383643513239455e27ca7/docs/handoff/from-builder-20261018T143000-ami-verified-repoint-and-branches-done.md), §4 Branches). Which branch an applied patch lands on is unverified (see Unverified). Done when `git status` shows your branch based on it. 3. **A recipe change** (a new package or a version bump) follows `contrib-send-a-recipe-change.md`. Done when the rule's steps hold. 4. **Prepare the mail.** `git format-patch origin/unstable..` writes patch files for your local changes ([perlgit(1)](https://solnix.io/docs/man/perlgit.1), Patch workflow). List threads carry `[PATCH]`, a revision `[PATCH v2]` (design §1). Plain text or `.patch`/`.diff` attachments; no HTML, executable attachments or compressed archives; under 2 MiB, each text part under 512 KiB ([Handbook: Contributing](https://solnix.io/docs/handbook/contributing#mailing-lists), Mailing lists). Done when the `.patch` files exist and the cover letter says what changed, why, and how you tested it. 5. **Stop and hand over.** The human sends it to `hackers@solnix.io`. New senders are moderated; posts, author addresses included, are public and may be mirrored (same section). An agent never sends mail. Done when the human has the files. A fix to these skills goes the same way: a patch to `hackers@solnix.io` against `codeberg.org/solnix/skills` ([handoff: 20261105-skills-review-request.md](https://codeberg.org/solnix/solnix-infra/src/commit/807157bf3453500cc1b383643513239455e27ca7/docs/handoff/20261105-skills-review-request.md), How to reply). ## Report a bug Check `package_status {pname}` and `search_handbook` first. Then give the human a report for `hackers@solnix.io` with: what you did, what you expected and what happened; the generation (`beadm list`); the artifact (`svcs -x` and the service log, `pstack` or `mdb` output, `crash.` for a panic, `fmadm faulty`); the `/nix/store` paths involved ([Handbook: Debugging](https://solnix.io/docs/handbook/debugging#reporting-a-bug-to-solnix), Reporting a bug to Solnix). A crash dump can hold confidential memory: ask before attaching one. A bug that reproduces on stock illumos with no Nix likely belongs upstream at illumos.org. The Codeberg issue tracker also takes reports (Handbook: Contributing). ## Report a security issue Never on a public list. The human mails `security@solnix.io` with the package, edition, the issue and a reproducer. Embargoed work stays on `security@` until the fix and the advisory go out together (design §1, §5.7). Workflow: `workflows/report-a-cve.md`. ## Write documentation Handbook chapters live in the site repo at `handbook/src/.md` ([handoff: bittorrent-cache-shim.md](https://codeberg.org/solnix/solnix-infra/src/commit/807157bf3453500cc1b383643513239455e27ca7/docs/handoff/bittorrent-cache-shim.md)); every page has an edit link (Handbook: Contributing, Ways to help). Follow `steering/voice.md` and `steering/honesty-over-hype.md`. Done when the chapter builds and every claim links a man page, a handbook section or a commit. ## Unverified - Whether the OS repo has an `OWNERS` file today, who is in it, and which paths it treats as leaf packages: the design's examples use placeholder names, and the copy of the repo used here does not include one. - Whether the eval-CI bot of design §10 exists now: on 2026-10-15 it did not (edition-branches handoff, Not yet). - Which branch an applied patch lands on: the edition-branches request gives `unstable` to contributors; the governance design commits to the default branch (§3, §5.3). - A required cover-letter format: no source sets one.