Contributing to IREE

We'd love to accept your patches and contributions to this project.

Note - coordinating efforts

Please file issues or reach out on any of our other communication channels before doing substantial work; this will ensure that others don't duplicate the work and that there's a chance to discuss any design issues.

Developer policies

Code of conduct

This project follows the LF Projects code of conduct.

Developer Certificate of Origin

Contributors must certify that they wrote or otherwise have the right to submit the code they are contributing to the project.

Expand to read the full DCO agreement text

By making a contribution to this project, I certify that:

1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

3. The contribution was provided directly to me by some other person who certified 1., 2. or 3. and I have not modified it.

4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Signing is enforced by the DCO GitHub App (see also the dcoapp/app repository).

The DCO check requires that all commits included in pull requests either are cryptographically signed by a member of the repository's organization or include a Signed-off-by message as a git trailer.

Crypographically signing commits

This is the recommended approach for frequent contributors!

For members of the repository's organization (see obtaining commit access), commits that are signed do not require the Signed-off-by text. See these references:

• Signing commits (generate key, add to https://github.com/settings/keys, git commit -S)

• SSH commit signature verification (recommended if you already use SSH keys with GitHub) and Signing Git Commits with SSH Keys (streamlined version of the previous page).

  SSH keys can be added at https://github.com/settings/ssh/new (Note that even if you have added your SSH key as an authorized key, you need to add it again as a signing key).

  Then,

  # Sign commits automatically
  git config --global commit.gpgsign true
  git config --global tag.gpgsign true
  
  # Sign using SSH, not GPG
  git config --global user.signingkey ~/.ssh/id_rsa.pub
  git config --global gpg.format ssh
  
  # Create an "allowed_signers" file
  echo your@email `cat ~/.ssh/id_rsa.pub` > ~/.ssh/allowed_signers
  git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
  

• Generating GPG keys (alternative to using SSH keys)

  GPG keys can be added at https://github.com/settings/gpg/new, then:

  # Sign commits automatically
  git config --global commit.gpgsign true
  git config --global tag.gpgsign true
  

Adding Signed-off-by to commits

This requires less setup and is suitable for first time contributors.

Contributors sign-off their agreement by adding a Signed-off-by line to commit messages:

This is my commit message

Signed-off-by: Random J Developer <random@developer.example.org>

• Git will automatically append this message if you use the -s option:

  git commit -s -m 'This is my commit message'
  

• Users of Visual Studio Code can add "git.alwaysSignOff": true, in their settings

• See .git/hooks/prepare-commit-msg.sample for how to automatically add this using a git hook

AUTHORS, CODEOWNERS, and MAINTAINERS

The AUTHORS file keeps track of those who have made significant contributions to the project.

• If you would like additional recognition for your contributions, you may add yourself or your organization (please add the entity who owns the copyright for your contributions).
• The source control history remains the most accurate source for individual contributions.

The .github/CODEOWNERS file lets maintainers opt in to PR reviews modifying certain paths.

• Review is not required from a code owner, though it is recommended.

The MAINTAINERS.md file documents official maintainers for project components.

Coding policies

Coding style guidelines

Most of the code style is derived from the Google Style Guides for the appropriate language. The C++ compiler portion of the project follows the MLIR/LLVM style guide.

We use pre-commit to run assorted formatters and lint checks. The configuration file at .pre-commit-config.yaml defines which "hooks" run.

• To run these hooks on your local commits, follow the pre-commit installation instructions.
• Individual formatters like clang-format (C/C++) and Black (Python) can also be set to run automatically in your editor of choice.

Note

Improvements to code structure and clarity are welcome but please file issues to track such work first. Pure style changes are unlikely to be accepted unless they are applied consistently across the project.

Testing policy

With few exceptions, features should be accompanied by automated tests.

We use a mix of in-tree and out-of-tree unit and integration tests. For more information about the types of tests used across the project, refer to the testing guide.

GitHub policies

Code reviews

All submissions, including submissions by maintainers, require review. We use GitHub pull requests (PRs) for this purpose. Consult GitHub Help for more information on using pull requests.

• Please keep PRs small (focused on a single issue) to make reviews and later culprit-finding easier.
• You may see trusted core contributors bending this rule for project maintenance and major subsystem renovation. If you feel like the rules aren't working for a certain situation, please ask as we bias towards pragmatism for cases that require it.

GitHub Actions workflows

We use GitHub Actions to automatically build and test various parts of the project.

• Most presubmit workflows will only run automatically on PRs if you are a project collaborator. Otherwise a maintainer must approve workflow runs. If you are sending code changes to the project, please request commit access, so that these can run automatically.
• It is generally expected that PRs will only be merged when all checks are passing. In some cases, pre-existing failures may be bypassed by a maintainer.

Tip - adjusting workflow behavior

Some workflows only run on commits after they are merged. See the CI behavior manipulation section below to learn how to customize this behavior.

Merging approved changes

After review and presubmit checks, PRs should typically be merged using "squash and merge".

• The squashed commit summary should match the PR title and the commit description should match the PR body (this is the default behavior). Accordingly, please write these as you would a helpful commit message.

It is assumed that the PR author will merge their change unless they ask someone else to merge it for them (e.g. because they don't have write access yet).

Obtaining commit access

Access to affiliated repositories is divided into tiers:

Tier	Description	Team link
Triage	New project members should typically start here Can be assigned issues Can apply labels to issues / PRs Can run workflows without approval	iree-triage
Write	Established project contributors should request this access Can merge approved pull requests Can create branches	iree-write
Maintain/Admin	Can edit repository settings Can push to protected branches	Added case-by-case

All access tiers first require joining the iree-org GitHub organization.

Fill out this form to request access

Once you are a member of the iree-org GitHub organization, you can request to join any of the teams on https://github.com/orgs/iree-org/teams.

Branch naming

Most work should be done on repository forks. For developers with write access, when creating a branch in the common iree-org/iree repository, please follow these naming guidelines:

Branch type	Naming scheme	Example
Single user	users/[username]/*	users/cooldeveloper/my-awesome-feature
Shared feature branch	shared/*	shared/pytorch-performance-sprint
Dependency updates	integrates/*	integrates/llvm-20240501

Branches that do not meet these guidelines may be deleted, especially if they appear to be stale.

Tips for contributors

Tool recommendations

Program or tool	Description
Visual Studio Code (VSCode)	The most commonly used editor amongst IREE developers
Ccache	A fast C/C++ compiler cache. See the CMake with ccache page
GitHub CLI	A CLI for interacting with GitHub
"Refined GitHub" browser extensions	Extension that add features to the GitHub UI

Build systems

IREE supports building from source with both Bazel and CMake.

• CMake is the preferred build system and offers the most flexible configuration options
• Bazel is a stricter build system and helps with usage in Google's downstream source repository
• Certain dependencies (think large/complex projects like CUDA, TensorFlow, PyTorch, etc.) may be difficult to support with one build system or the other, so the project may configure these as optional

Continuous integration (CI)

IREE uses GitHub Actions for CI. The primary CI is configured in the ci.yml workflow file.

Self-hosted runners

In addition to the default runners GitHub provides, IREE uses self-hosted runners to run many of its workflow jobs. These enable access to additional compute and custom configurations such as accelerators.

• Configuration for GCP runners is stored at build_tools/github_actions/runner/
• Configuration for other runners is done manually as needed

CI behavior manipulation

The setup step of the CI determines which CI jobs to run. This is controlled by the configure_ci.py script. It will generally run a pre-determined set of jobs on presubmit with some jobs kept as post-submit only. If changes are only to a certain set of excluded files that we know don't affect CI (e.g. Markdown files), then it will skip the jobs.

You can customize which jobs run using git trailers in the PR description.

The available options are

ci-skip: jobs,to,skip
ci-extra: extra,jobs,to,run
ci-exactly: exact,set,of,jobs,to,run
skip-ci: free form reason
skip-llvm-integrate-benchmark: free form reason
benchmark-extra: extra,benchmarks,to,run
runner-env: [testing|prod]

Using skip-ci

skip-ci skips all jobs. It is mutually exclusive with the other ci-* options and is synonomous with ci-skip: all.

skip-ci: free form reason

Using ci-skip, ci-extra, ci-exactly

The ci-* options instruct the setup script on which jobs to include or exclude from its run. They take a comma-separated list of jobs which must be from the set of top-level job identifiers in the ci.yml file or the special keyword "all" to indicate all jobs.

ci-skip: jobs,to,skip
ci-extra: extra,jobs,to,run
ci-exactly: exact,set,of,jobs,to,run

• ci-skip removes jobs that would otherwise be included, though it is not an error to list jobs that would not be included by default.
• ci-extra adds additional jobs that would not have otherwise been run, though it is not an error to list jobs that would have been included anyway. It is an error to list a job in both "skip" and "extra".
• ci-exactly provides an exact list of jobs that should run. It is mutually exclusive with both "skip" and "extra".

In all these cases, the setup does not make any effort to ensure that job dependencies are satisfied. Thus, if you request skipping the build_all job, all the jobs that depend on it will fail, not be skipped.

Using benchmark-extra, skip-llvm-integrate-benchmark

benchmark-extra: extra,benchmarks,to,run
skip-llvm-integrate-benchmark: free form reason

Benchmarks don't run by default on PRs, and must be specifically requested.

The benchmark-extra option allows specifying additional benchmark presets to run as part of benchmarking. It accepts a comma-separated list of benchmark presets. This combines with labels added to the PR (which are a more limited set of options). See the benchmark suites documentation.

Benchmarks do run by default on PRs detected to be an integration of LLVM into IREE, but this behavior can be disabled with skip-llvm-integrate-benchmark.

Using runner-env

The runner-env option controls which runner environment to target for our self-hosted runners. We maintain a test environment to allow testing out new configurations prior to rolling them out. This trailer is for advanced users who are working on the CI infrastructure itself.

runner-env: [testing|prod]

CI configuration recipes

Copy/paste any of these at the bottom of a PR description to change what the CI runs.

• Also run Windows and macOS builds that are normally post-merge only:

  ci-extra: build_test_all_windows,build_test_all_macos_arm64,build_test_all_macos_x86_64
  

• Also run GPU tests on NVIDIA A100 runners (opt-in due to low availability):

  ci-extra: test_nvidia_a100
  

• Skip all CI builds and tests, e.g. for comment-only changes:

  skip-ci: Comment-only change.
  

• Only run Bazel builds, e.g. for changes only affecting Bazel rules:

  ci-exactly: build_test_all_bazel
  

For example, this PR opted in to running the build_test_all_windows job:

The enabled jobs can be viewed from the Summary page of an action run: