--- title: Send a gate change upstream through an illumos issue, review and an RTI to the core team area: gate impact: HIGH tags: [illumos-gate, rti, advocates, gerrit, code-review, commit-message, flag-day, ipd, upstream] verified: 2026-11-05 --- # Send a gate change upstream through an illumos issue, review and an RTI to the core team A change reaches illumos-gate after the core team accepts your request to integrate (RTI). The RTI needs an issue, at least one reviewer, testing notes, the `git pbchk` output, a clean `mail_msg` from a full nightly, and the change. Leave out what does not apply ("shrink to fit"), but if the core team member says a part applies, you must address it. The human sends the mail; an agent drafts it (`steering/upstream-ai-policies.md`). **Antipattern** ```sh git commit -m "fix xhci quiesce" # no issue number; the format is " " # a blank line between the synopsis and the Reviewed by: lines, or your own "Approved by:": the integrating core team member adds that line # three commits for one issue: squash them (git rebase -i origin); one commit per change # mail_msg from nightly -i, or tests run only on a downstream build carrying other changes (the Solnix kernel) # the RTI mailed to one core team member: send it to advocates@lists.illumos.org # an agent sending the RTI: the human reviews and sends it ``` **The Solnix way** ```sh # The Solnix OS repo consumes illumos-gate at a pinned rev (ac45d71fc2) and carries its own gate changes as patches, # not as a fork (nix-conventions.md: "carry illumos changes as patches/ + inline build tweaks"): # pkgs/illumos/kernel-nd.nix applies nine patches from scripts/patches/ (0001 to 0010, no 0004: tscc_pit, tzmon, # usbecm, xhci, zfs, opteron_pcbe) to the pinned source with patch -p1 --fuzz=0, then greps that each landed; # pkgs/illumos/patches/ also holds ena-default-mtu-1500.patch; its README says to apply it to the gate tree # before the proto build. # A change to that patch set is a Solnix patch to hackers@solnix.io (steering/email-patch-governance.md). # A change for illumos itself: build illumos-gate with only your change and follow the illumos way below. ``` docs/post-stable-backlog.md (PS-17) plans quiesce fixes, not yet written, for upstream illumos (xhci: "a small upstream illumos change; send it upstream"; pchsmbus, with a condition in the same bullet: read PS-17 before touching it). **The illumos way** (upstream illumos-gate) ```sh illumos_issues {query: "...", status: "open"} # this server: an existing issue? else create one # larger work: an IPD (illumos Project Discussion, github.com/illumos/ipd); ask developer@ or IRC first git remote add illumos @code.illumos.org:illumos-gate.git # Gerrit: the bug-tracker account and its ssh key scp -O @code.illumos.org:hooks/commit-msg .git/hooks/ # adds the Change-Id: footer Gerrit tracks git push illumos HEAD:refs/for/master # opens the review; amend, push again git commit --amend # message, no blank line before the Reviewed by: lines: # 12975 Main B bus undervolt prevents forward progress # Portions contributed by: (only if several authors) # Reviewed by: git log --stat -v origin/master.. # the change set description for an RTI with a patch, without the Change-Id: line ``` RTI mail to `advocates@lists.illumos.org`, under 2 MB, subject naming the issues or the work: the issue link; the Gerrit link or an attached `git format-patch`; the `git pbchk` output (optional if it prints nothing and exits 0); a clean `mail_msg` from a full nightly with GCC 10 primary and GCC 14 and smatch shadows, built straight after a clean build of the previous commit; how you tested (or "the testing notes are in the issue"). The issue holds your analysis (DTrace or mdb output) and the testing notes. List only reviewers who are satisfied; note any dissent. No reply in a day or two: a friendly reminder on the same thread. After integration, abandon the Gerrit change with "integrated". illumos tries to announce changes that impact other developers in "flag day" mail to the developer list; the Flag Days page lists them. Read it when the build has a problem you cannot explain. **The difference.** How you install and test your build depends on the distribution you test on (illumos docs, Contributing, Testing). What differs for Solnix is the starting tree and the build: the Solnix kernel is the pinned gate plus Solnix's patches, built without nightly's userland (kernel-nd.nix), so neither its build log nor tests on it are the clean upstream build the RTI asks for: rebuild on OpenIndiana or OmniOS (rules `gate-build-nightly-bldenv.md`, `gate-checks-pbchk-cstyle.md`). **Check.** `git log --stat -v origin/master..` shows one commit whose message starts with one or more ` ` lines, then, with no blank line, any `Portions contributed by:` lines and the `Reviewed by:` lines, and no `Approved by:`. The Gerrit hook's `Change-Id:` footer follows a blank line. **Unverified** - Which of the kernel-nd.nix patches have been sent upstream or have an illumos issue: the sources do not say. - Whether illumos has a written policy on AI-assisted contributions: none in the illumos sources read here. **Sources** - [illumos docs: Contributing](https://illumos.org/docs/contributing/) (MPL-2.0), Finding An Area To Contribute To (issue, IPD); Testing (All changes; downstream forks); Code Review (Gerrit; at least one reviewer; Ensuring adequate review); Submitting A Patch (RTI contents, no blank line, Change-ID, Approved by, advocates@, 2MB, Abandon) - [illumos docs: Code Review with Gerrit](https://illumos.org/docs/contributing/gerrit/) (MPL-2.0), Authentication; 2. Clone the software and install the hook script; 3. Prepare your commit and push; 4. Update your change - [illumos docs: Flag Days](https://illumos.org/docs/developers/flagdays/) (MPL-2.0), introduction; [Building illumos](https://illumos.org/docs/developers/build/), Missed Flag Day - [Developer's Guide: Integrating](https://illumos.org/books/dev/integrating.html) (PDL), RTI process (The Requirements; Shrink to Fit; Review; Testing; nightly mail_msg); Submitting; When the Core Team Drop the Ball - [Developer's Guide: Workflow](https://illumos.org/books/dev/workflow.html) (PDL), Squashing Commits and Commit Messages; Combining Multiple Authors; Gerrit - [steering: upstream-ai-policies](https://solnix.io/skills/steering/upstream-ai-policies.md), illumos-gate; closing line (the human reviews and sends) - [steering: email-patch-governance](https://solnix.io/skills/steering/email-patch-governance.md), patches go to hackers@solnix.io - [.kiro/steering/nix-conventions.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/nix-conventions.md) (solnix 5a8e5ce), Three-repo split - [pkgs/illumos/kernel-nd.nix](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/pkgs/illumos/kernel-nd.nix) (solnix 5a8e5ce), header; `patches`; the patch loop and its greps - [pkgs/illumos/patches/ena-default-mtu-1500.README.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/pkgs/illumos/patches/ena-default-mtu-1500.README.md) (solnix 5a8e5ce), Applying - [docs/post-stable-backlog.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/post-stable-backlog.md) (solnix 5a8e5ce), PS-17 (xhci, pchsmbus)