snix/web/content/docs/guides/contributing.md

title	description	summary	date	lastmod	draft	weight	toc
Contributing			2025-03-14T14:14:35+01:00	2025-03-14T14:14:35+01:00	false	12	true

You want to start contributing? Nice!

We do use Gerrit for Code Review. It allows a more granular review (per-commit granularity rather than PR granularity), as well as keeping track as how commits change over time. It greatly simplifies the review process, and leads to overall more high-quality contributions.

While it might initially look a bit intimidating, you hopefully will spend less time learning its workflow than writing actual Snix code.

{{}} This assumes you have the repo already cloned and the necessary tools installed as described in [Building Snix]({{< relref "./building" >}}), so make sure you went through these instructions first. {{}}

Creating a Gerrit account

• Navigate to our Gerrit instance. Hit the "Sign in" button (which allows SSO with some common IdPs)
• In the User settings, paste an SSH public key and hit the "Add New SSH key" button. ¹
• Alternatively, you can also create "HTTP Credentials" (though saving the HTTP password is messy).

Update your git remote URL

Instead of trying to push to Forgejo, reconfigure your git remote URL to interact with Gerrit directly.

Replace $USER with your Username shown in the Gerrit settings.

If using SSH authentication:

$ git remote set-url origin "ssh://$USER@cl.snix.dev:29418/snix"

If using HTTP authentication:

$ git remote set-url origin "https://$USER@cl.snix.dev/a/snix"

Install the commit-msg hook

Gerrit uses a commit-msg hook to add a Change-Id: … field to each commit message if not present already. This allows Gerrit to identify new revisions / updates of old commits, and track them as new revisions of the same "CL" ².

To install the commit-msg hook, run the following from the repo root:

mkdir -p .git/hooks
curl -Lo .git/hooks/commit-msg https://cl.snix.dev/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

{{< callout context="tip" title="Did you know?" icon="outline/rocket" >}} Gerrit refuses receiving commits without these Change-Id: … fields.

If you already have some local commits without Change-Id field, git commit --amend them after installing the commit-msg hook to add them. {{< /callout >}}

Push your changes

Do some local changes, and push them to Gerrit as follows:

$ git push origin HEAD:refs/for/canon

Gerrit will print links to newly created CLs to your terminal.

If you want to update/edit your CL, simply squash these changes into your local commit and push again.

The Gerrit model

If do not have experience with the Gerrit, consider reading the Working with Gerrit: An example or Basic Gerrit Walkthrough — For GitHub Users.

Some more tips:

• Assign a reviewer to review your changes.
• React on comments and mark them as resolved once you did.
  • Comments are only "Drafts" (stored server-side) until you send them off. This can be done by the Reply button on the top, for example.
• Once CI is green, it's up to the Author of the CL to submit, not the reviewer. If you want a bot to automatically submit in this case, you can add the Autosubmit+1 label.
• Rebase on origin/canon regularly. You cannot push if you still have an old version of a now-submitted CL in your git log.

{{< callout context="tip" title="Did you know?" icon="outline/rocket" >}} You can immediately assign reviewers and other fields while pushing a new/updated change, by adding it to the push URL.

$ git push origin HEAD:refs/for/canon%r=alice,cc=bob,l=Autosubmit+1,publish-comments

• will set alice as a reviewer
• will set bob as CC
• adds the Autosubmit+1 label
• publishes any outstanding draft comments {{< /callout >}}

---

1. currently, ssh-*-sk keytypes are not supported, so use an ssh-ed25519 key. ↩︎

2. abbreviation for "change list", and the review unit in Gerrit. ↩︎