--- title: Send a recipe change (a new package or a version bump) as a patch to hackers@solnix.io area: contrib impact: MEDIUM tags: [contributing, recipe, recipes.tsv, hackers, format-patch, cover-letter, governance, cache] verified: 2026-11-05 --- # Send a recipe change (a new package or a version bump) as a patch to hackers@solnix.io A recipe change is a patch to the Solnix OS repo: the derivation under `pkgs/illumos/` and, once the build team has built it, a new row in `docs/registry/recipes.tsv`. It goes by email to `hackers@solnix.io`; embargoed security work goes to `security@solnix.io`. solnix.io accepts a submission only for a path the served copy of recipes.tsv lists, so a merged patch is not yet a served package. **Antipattern** ```sh # a pull request on Codeberg: the handbook says there is no PR-to-patch bridge; send patches by email # typing an `out` hash into recipes.tsv, or copying one from an old row # rewriting or re-sorting recipes.tsv: rows are appended # submitting a NAR for your change: solnix.io accepts a submission only for an out the served recipes.tsv lists # an agent mailing the patch: the human sends it ``` **The Solnix way** ```sh git clone -b unstable https://git.solnix.io/solnix.git && cd solnix # unstable: the development branch (see Unverified) # edit the package's derivation under pkgs/illumos/ (rule recipe-write-a-solnix-recipe) nix build .#packages.x86_64-solaris. # it must build; on illumos, with store tools on the build PATH nix-store --realise --check "$(nix-store -q --deriver result)" # a second build gives the same bytes git add pkgs/illumos/ && git commit && git format-patch origin/unstable.. # patch files for your local changes # list threads carry [PATCH], a revision [PATCH v2] (design §1) # cover letter: what changed (pname, old and new version, url, sha256) and why; the build command and its result; # the --check result; the systems built for. Plain text or .patch/.diff; message under 2 MiB, each text part under 512 KiB. # Stop. The human sends the files to hackers@solnix.io (embargoed security work: security@solnix.io). ``` On the thread, per the governance design (in progress) and `steering/email-patch-governance.md`: votes are `+1`/`0`/`-1`, an owner's `-1` blocks, and a built artifact also needs a reproducibility quorum. Who the owners are is unverified (see Unverified). The design also adds owner approval of the reproduced hash (an owner quorum for `pkgs/illumos/**`, §5.5); its §10 lists the OWNERS approval checker as not built yet. The build team's repo copy of recipes.tsv is the source of truth: the team appends one row per output, with the `out` its build produced. The infra team reviews and serves the file. The build team then submits one leaf at a time, deps first; the site signs with the 8UNr key. Until the `out` is listed and in the cache, Nix on a user's machine falls back to building it from source. **The illumos way** (OpenIndiana) ```sh git clone https://github.com//oi-userland && cd oi-userland # your fork on GitHub gmake setup # first use: tools and a local IPS repository git checkout -b my_feature # a new branch for each component you add or change cd components//foo && vi Makefile # COMPONENT_VERSION, COMPONENT_ARCHIVE_URL, COMPONENT_ARCHIVE_HASH # a new package also needs foo.p5m (gmake sample-manifest, then edit) gmake publish # to your local IPS repository; then pkg install and test git add Makefile *.p5m && git commit git push my_feature # then a pull request to OpenIndiana/oi-userland, asking for review # once committed, Jenkins builds it and publishes the package to the /hipster repository ``` **The difference.** OpenIndiana takes a pull request on GitHub and its CI publishes what is committed. Solnix takes an emailed patch, reviews it on `hackers@`, and publishes a recipe's `out` once the build team built it, the infra team serves it in recipes.tsv, and the site signed it. Solnix has no IPS manifest and no `pkg` (rule `recipe-write-a-solnix-recipe.md`). **Check.** Once the row is served, `curl -s https://cache.solnix.io/registry/recipes.tsv | grep ` prints the row, and `package_status {pname}` shows the version as served. **Unverified** - How the OS repo's `OWNERS` file assigns `pkgs/illumos/**` today: the governance design shows placeholder names, and the repo copy used here has no `OWNERS` file. - A required cover-letter format: no source sets one. - Whether the design's eval-CI bot exists now: on 2026-10-15 it did not (edition-branches handoff). - Which branch an applied patch lands on: the edition-branches request gives `unstable` to contributors and `26.11` to maintainers; the governance design commits to the default branch (§3, §5.3). - Whether a contributor outside the build team should add the recipes.tsv row: the sources describe the build team adding rows from its own builds. **Sources** - [Handbook: Contributing](https://solnix.io/docs/handbook/contributing#mailing-lists) (site 307b67f), Repos; Mailing lists (plain text or .patch/.diff, 2 MiB, 512 KiB, no PR-to-patch bridge) - [asset-lifecycle-governance-v2.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/design/asset-lifecycle-governance-v2.md), §1 Lists ([PATCH], [PATCH v2]); §3 state machine; §5.1 votes; Status; §5.4 owner approval of the artifact; §8.1 reproduction quorum; §10 (components still needed) - [steering: email-patch-governance](https://solnix.io/skills/steering/email-patch-governance.md), votes; owner -1; embargoed security work to security@; the human sends the mail - [.kiro/steering/builder-queue.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/builder-queue.md) (solnix 5a8e5ce), The contract (recipes.tsv is the configuration; our file is the source of truth, the infra team reviews and publishes it; `out` is the authority anchor; one leaf per submission, deps first; the site signs with 8UNr) - [.kiro/steering/nix-conventions.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/nix-conventions.md) (solnix 5a8e5ce), Shared-file concurrency (append rows, don't rewrite) - [AGENTS.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/AGENTS.md) (solnix 5a8e5ce), solnix.io belongs to the infra team (submit only what the served recipes.tsv authorizes) - [docs/cache-submit-onboarding.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/cache-submit-onboarding.md) (solnix 5a8e5ce), Rules that will reject your submission; Current status (`https://cache.solnix.io/registry/recipes.tsv`) - [docs/registry/DROPPED-x86_64-regen.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/registry/DROPPED-x86_64-regen.md) (solnix 5a8e5ce), do not copy an old hash back in - [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), What Solnix should have now (a request: `unstable` for applied `hackers@` patches, `26.11` maintainers only); Not yet: `staging`, update trains, channel branches (the eval/build CI bot "doesn't exist yet") - [steering: edition-policy](https://solnix.io/skills/steering/edition-policy.md), `main` and `unstable` move ahead of the edition; follow development with `?ref=unstable` - [perlgit(1)](https://solnix.io/docs/man/perlgit.1) (Solnix pkgs.solnix.perl), Patch workflow (`git format-patch -M blead..` creates a patch file for your local changes) - [handoff: 20261022-orchestrator-403-fixed-and-inbox-replies.md](https://codeberg.org/solnix/solnix-infra/src/commit/807157bf3453500cc1b383643513239455e27ca7/docs/handoff/20261022-orchestrator-403-fixed-and-inbox-replies.md), §7 Mirror (git.solnix.io serves `main` and `unstable`) - [handoff: 20261015-recipe-outputs-missing-from-cache.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/20261015-recipe-outputs-missing-from-cache.md), Finding (an unserved path falls back to building from source) - [handoff: from-builder-20261102T194222-rows1-b1-rows/README.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/from-builder-20261102T194222-rows1-b1-rows/README.md), What we ask; Checks (store-only PATH, `nix-store --realise --check`) - [handoff: from-builder-20261025T010000-main-2d78d39-recipe-rows.md](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/from-builder-20261025T010000-main-2d78d39-recipe-rows.md), Evidence (`nix build .#packages.x86_64-solaris.`) - [rule recipe-write-a-solnix-recipe.md](https://solnix.io/skills/solnix/rules/recipe-write-a-solnix-recipe.md), the derivation, the row, the publish gate - [OpenIndiana docs: Building with oi-userland](https://docs.openindiana.org/dev/userland/) (PDL), Using OpenIndiana's unified build system (Jenkins, /hipster); Downloading oi-userland (fork, gmake setup); Creating Makefile; Creating p5m files; Publishing packages; Contributing changes back (branch, commit, push); Asking for change integration (Pull Request)