How to Prepare and Submit a Haiku Patch That Maintainers Can Review

Haiku core changes are reviewed through the project’s Gerrit service, not GitHub pull requests. A reviewable patch starts before editing: reproduce one problem on a known revision, build the unmodified target, read subsystem conventions, and agree on direction for architectural work.

Choose and reproduce one problem

Search Haiku’s bug tracker and existing Gerrit changes. Pick a bounded issue with hardware/input you can test. Comment before duplicating active work. For behavior changes without a ticket, discuss the design on the relevant development channel when it affects public API, storage formats, kernel interfaces, or UI policy.

Record Haiku revision/architecture, exact reproduction, expected result, actual result, logs/crash report, and a minimal testcase. Build/run the baseline so an environment problem is not mistaken for a code defect.

Avoid combining cleanup, formatting, renaming, and functional change. One logical problem per review lets maintainers reason about risk and revert independently.

Prepare the official repository and Gerrit identity

Follow Haiku’s current “Get Source / Pushing Patches” guide. Create accounts/SSH keys as required by review.haiku-os.org, clone the official repository, and use its authenticated Gerrit remote for submission. The guide explicitly says GitHub pull requests for the Haiku OS repository cannot be accepted.

Install Gerrit’s commit-msg hook using the command shown by the current Gerrit documentation. It adds a Change-Id trailer so amended patchsets remain one review. Do not invent/reuse another change’s ID.

Create a local topic branch and keep the upstream branch current without rewriting unrelated commits. Verify:

git status --short
git diff --check

Never include generated output, credentials, crash cores, build directories, or editor files.

Implement to Haiku conventions

Read the coding guidelines and nearby source. Match indentation, naming, ownership, status handling, locking, and error conventions of the subsystem. Public/user strings need localization macros; new files need correct copyright/license headers.

Treat user/kernel and IPC data as untrusted. Validate sizes/types and preserve ABI/API behavior unless the review explicitly changes it. Keep error paths and teardown symmetric; add comments for non-obvious invariants, not restatements of code.

Add a focused regression test where the subsystem has infrastructure. A test should fail on the baseline for the intended reason and pass with the patch. Avoid timing assumptions or dependence on one developer’s settings/hardware unless the test is explicitly hardware-specific.

Build and exercise the actual boundary

Build the narrow target first with Haiku’s Jam rules, then its direct tests. Rebuild dependents when headers, resources, libraries, packages, or ABI change. A linked object in generated/ does not prove the package/image being booted contains it.

For kernel, driver, package, boot, app_server, or system-server changes, build a bootable image and test in a VM or relevant hardware. Preserve configure command, exact Jam target, build log, and architectures. Test failure paths and cleanup, not only the successful click.

Run surrounding tests and check for warnings. Reproduce the original defect, verify the fix, then revert/test or compare baseline if causality is uncertain. Document anything you could not test.

Create a clean commit

Review every hunk with git diff. Stage only intended files. The commit subject should be concise and name the subsystem; the body explains the problem, cause, solution, user-visible effect, and important tradeoffs. Reference the ticket in the project’s accepted format without claiming it fixed before review/testing.

Keep the Gerrit-generated Change-Id intact. Do not squash unrelated history into the patch or add a “v2” commit for review changes. Authors must certify/licence contributions under Haiku’s rules; do not submit code copied from incompatible sources.

Push the commit to Gerrit’s review ref using the exact command in the current guide, commonly the branch’s refs/for/... target. Open the resulting review, add the ticket/context, and list tests/architectures.

Respond with new patchsets

Read inline and summary comments as technical collaboration. Reproduce reviewers’ concerns, ask when intent is unclear, update code/tests, then amend the existing commit:

git commit --amend

Keep the same Change-Id and push again to create a new patchset in the same review. Reply to addressed comments and explain disagreements with evidence. Do not mark issues resolved merely because code changed nearby.

Before each patchset, rebase as requested, inspect the complete diff against target branch, rebuild impacted targets, rerun tests, and update the testing note. If design changes substantially, ensure the commit message still describes reality.

Close the loop

After merge, verify the change in the integration/nightly build when relevant and update the ticket. Watch for buildbots or regressions. If the patch is abandoned, leave a clear review comment so another contributor understands its state.

A maintainable contribution is not the largest diff. It is the smallest evidence-backed change another developer can build, understand, test, review, and revise without reconstructing the author’s environment.

Related:

Sources: