Contributing to Helium

March 16, 2026 · View on GitHub

This repository contains Helium's shared Chromium patches, resources, and development tooling. Platform-specific packaging and build environments live in the platform repositories:

The same contribution guidelines apply to all platform repos.

Before you start

General

  • For platform-specific issues or features, open the issue or PR in the related platform repository instead of this one.
  • Do not use AI to generate issue or PR descriptions. You will get banned for spam without review. We want contributions from people, not bots.

Issues

  • Search existing issues before opening a new bug report or feature request.
  • When creating an issue, please follow the template and be as specific as possible.
  • Please do not create duplicate issues. We reserve the right to ban you for repeatedly wasting our time through ignorance.

Contributions

  • For non-trivial changes, start with an issue and wait until a maintainer confirms the bug or agrees that the feature should be implemented.
  • If an issue you want to work on is stale, mention an active maintainer and show your intent to contribute.
  • Please do not use AI for contributing if you don't fully understand its output. We will permanently ban you if you spam our repos with AI slop.

Development

macOS is our primary development platform, so it's the recommended development environment for community contributions.

Linux packaging includes a similar development script, so the same guide can be applied there too.

> See development docs in macOS repo

Working with patches

Most code changes in this repository are maintained as quilt patches applied on top of Chromium.

  • Don't edit files in patches/ directly unless you know exactly what you're doing.
  • Make code changes in the Chromium source tree, then refresh the affected patch.
  • Keep patch ordering and ownership intact.
  • Follow the existing vendor grouping under patches/ unless maintainers ask for something different.

When working in a platform repository, the usual workflow is:

  1. Load the development environment.
  2. Merge the patch series and push all patches.
  3. Use quilt in build/src to create or edit a patch.
  4. Refresh patches after your changes.
  5. Unmerge the series, verify, commit.

Code style

  • Follow Chromium style and conventions.
  • Prefer existing Chromium or Helium patterns over introducing new abstractions.
  • Keep changes focused and minimal.
  • Proofread surrounding code before submitting.
  • When adding new Helium-authored files to the Chromium tree, include the Helium copyright header used in other patches.
  • Refer to existing Helium patches for guidance if necessary.

Git style

Clean commit messages

We use commit titles that are similar to Linux Kernel Style, but with a more flexible scope-first format. And without the email prefix, obviously.

Examples of titles from recent history as of writing:

- helium/ui/layout: add a ⌘+S shortcut to toggle vertical tabs
- helium/ui/pdf-viewer: fix stuck width when sidebar's collapsed
- deps: update ublock to 1.70.0
- merge: update to chromium 146.0.7680.75
- helium/core/keyboard-shortcuts: update command state correctly

The part before the colon should describe the area being changed (scope), and the part after the colon should explain the change itself.

  1. Pick the most helpful scope for the change.
  2. Do not use generic scopes like "feat" or "chore".
  3. Keep titles specific and meaningful rather than generic.
  4. If the change needs extra context, add a body explaining why it was made and what changed.

Make sure that the title is 65 chars long or shorter. This is needed for squash merging with a PR reference, so that the total length is 72 chars or under.

72 is a common length limit before the title gets wrapped into the body in most places (such as GitHub). For example, this final commit title is exactly 72 characters long:

helium/ui/customize: add change wallpaper button, fix visibility (#1053)

If a multi-commit pull request contains uninformative or malformed commit titles, maintainers will ask you to rewrite them before review/merge.

Clean commit history

Keep branch history tidy before opening a pull request.

  • If your changes are big, split them into several commits with a smaller scope.
  • If you find a bug in an unmerged commit, prefer folding the fix into the commit that introduced it.
  • Use interactive rebase extensively to maintain a clean and readable commit history in your branch.
  • Use git commit --amend when fixing the latest commit.
  • Use git commit --fixup=<hash> for older commits, then squash during an interactive rebase.
  • Use git cherry-pick <hash> for single-commit changes if a rebase is too complex.
  • If you rewrite commits that were already pushed, force push the branch with git push -f or alike.

This keeps the branch history easier to review, bisect, and revert.

Pull requests

Before opening a pull request, make sure that:

  • The change is tied to an approved feature request or confirmed bug.
  • The branch builds and runs without issues and has been thoroughly tested. Otherwise, the pull request is marked as draft.
  • The pull request description clearly explains the change scope. The description includes visuals (screenshots, videos) if applicable.
  • You mention which platforms you tested on.
  • The branch is rebased on main, or at least the latest Chromium milestone.

Small and focused pull requests are much easier to review. Please split your changes into several follow-up PRs if necessary.

Licensing

By contributing to Helium, you agree that your changes will be licensed under the repository's existing licensing terms.