icon: octicons/code-review-16

Contributing to IREE

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

!!! note “Note - coordinating efforts”

Please [file issues](https://github.com/iree-org/iree/issues/new/choose) or
reach out on any of our other
[communication channels](../../index.md#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

:octicons-code-of-conduct-16: Code of conduct

This project follows the LF Projects code of conduct.

:octicons-law-16: 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.

??? quote “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.

Cryptographically 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

:octicons-people-16: 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.

:octicons-code-16: Coding policies

:octicons-pencil-16: Coding style guidelines

Our formatting rules are enforced by language-specific formatters like clang-format for C++ and black for Python. In addition to formatting, we follow these coding standards:

Compiler

The C++ compiler portion of the project follows the MLIR style guide based on the LLVM coding standards. We also follow the recommendations of the LLVM Programmer's Manual.

IREE deviates from the MLIR style guide in the following ways:

We use braces with single-line if statements and loops.
We allow for static functions in anonymous namespaces to avoid repeatedly reopening/closing namespaces.
Pass declarations in TableGen (.td) files should use a Pass suffix (e.g., def FooBarPass), while the corresponding implementation file should not include the Pass suffix (e.g., FooBar.cpp, not FooBarPass.cpp).

Runtime

Most of the code style is derived from the Google Style Guides for the appropriate language.

Other

For code outside of the compiler/ and runtime/ subdirectories, follow the style used in existing files.

Formatting and Linting

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.

:material-test-tube: 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.

:simple-github: GitHub policies

:octicons-code-review-16: 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 or feature) to make reviews and later culprit-finding easier.
- You may see trusted core contributors bending above 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.
We require review comments to be addressed before merging, even when there is an approval from another reviewer. Unless stated otherwise, we treat request for changes as blocking. Reviewers may indicate that some comments requesting changes are optional (commonly by prefixing them with ‘nit’ or ‘optional’) -- use your best engineering judgement to decide whether to follow these suggestions or not.
If there are new comments requesting changes after a PR was merged, these comments should be addressed as well, either through follow-up discussion or code changes. Small issues may be fixed forward, but reviewers may also ask for your PR to be reverted. This is not a sign that your PR was faulty -- we prefer to err on the side of caution and reverting allows more time for design discussion.

:material-check-all: 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 - “Tip - adjusting workflow behavior”

Some workflows only run on commits after they are merged. See the
[CI behavior manipulation](#ci-behavior-manipulation) section below to
learn how to customize this behavior.

:octicons-git-pull-request-16: 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).

:octicons-git-merge-16: Obtaining commit access

Access to repositories is divided into tiers following the GitHub organization permissions model:

Tier	Description	Team links
Triage	New project members should typically start here :material-check: Can be assigned issues :material-check: Can apply labels to issues / PRs :material-check: Can run workflows without approval	iree-triage (access to most repositories)
Write	Established contributors can request this access :material-check: Can merge approved pull requests :material-check: Can create branches :material-check: Can re-run workflows	iree-write (access to most repositories)iree-turbine-write (access to iree-turbine)iree-fusilli-write (access to fusilli)
Maintain/Admin	:material-check: Can edit repository settings :material-check: Can push to protected branches	Added case-by-case

All access tiers first require joining the iree-org GitHub organization. To request membership in iree-org, send an email to iree-github-requests@lists.lfaidata.foundation with this template:

GitHub username:

Company/organization you are associated with:

Reason for requesting access:

[Send this email template to request access :fontawesome-solid-paper-plane:](mailto:iree-github-requests@lists.lfaidata.foundation?&subject=Requesting%20membership%20in%20iree-org&body=GitHub%20username:%0D%0A%0D%0ACompany/organization%20you%20are%20associated%20with:%0D%0A%0D%0AReason%20for%20requesting access:){ .md-button .md-button--primary }

If approved, an invitation will be sent to your GitHub account. You can also view the invitation link directly. Then, once you are a member of the organization, you can request to join any of the teams on https://github.com/orgs/iree-org/teams (note that some teams are nested under iree-triage, so click the caret to expand the list).

Write access is reserved for “established contributors” who have a track record of multiple high quality pull requests or reviews and have demonstrated familiarity with the contributing guidelines.

!!! question “Questions about access”

For questions about access policies, feel free to reach out on the
[`#github` channel](https://discord.com/channels/689900678990135345/1166024193599615006)
on IREE's Discord server, the <iree-github-requests@lists.lfaidata.foundation>
email list, or another of our
[communication channels](../../index.md#communication-channels) to discuss.

:octicons-git-branch-16: 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.

:octicons-hubot-16: AI tool use

We adopt the LLVM AI Tool Use Policy and require all AI-assisted contributions (Pull Requests, issues, design proposals) to be reviewed and understood by the author(s).

The key points include:

“Contributors must read and review all LLM-generated code or text before they ask other project members to review it.”
“Contributors are expected to be transparent and label contributions that contain substantial amounts of tool-generated content.” This can be done with the Assisted-by: tool-name or the Co-authored-by: tool-name tool@email trailer in PR descriptions.
“To ensure sufficient self review and understanding of the work, it is strongly recommended that contributors write PR descriptions themselves (if needed, using tools for translation or copy-editing).” This also extends to code documentation, issue descriptions, and design proposals.
“Contributors are responsible for ensuring that they have the right to contribute code under the terms of our license, [...]. Using AI tools to regenerate copyrighted material does not remove the copyright, and contributors are responsible for ensuring that such material does not appear in their contributions.”

We extend the LLVM policy with an exception for AI bot-authored contributions (e.g., updating dependencies, fixing build script, etc.); bot account may create Pull Requests as long as the bot maintainers ensure they are first in line and primarily responsible for reviewing those contributions.

Tips for contributors

Tool recommendations

Program or tool	Description
:material-microsoft-visual-studio-code: Visual Studio Code (VSCode)	The most commonly used editor amongst IREE developers
:simple-cmake: Ccache	A fast C/C++ compiler cache. See the CMake with `ccache` page
:simple-github: GitHub CLI	A CLI for interacting with GitHub
:simple-github: “Refined GitHub” browser extensions	Extension that add features to the GitHub UI

:material-hammer-wrench: 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

:octicons-server-16: Continuous integration (CI)

IREE uses GitHub Actions for CI. See our GitHub Actions documentation for full details.

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

??? info - “Using skip-ci”

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

``` text
skip-ci: free form reason
```

??? info - “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.

``` text
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_packages` job, all the jobs that depend on it will fail, not be
skipped.

CI configuration recipes

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

Skip all CI builds and tests, e.g. for comment-only changes:
```
skip-ci: Comment-only change.
```
Only run runtime builds:
```
ci-exactly: runtime
```
Only run ONNX tests:
```
ci-exactly: build_packages,test_onnx
```
Only run Bazel builds, e.g. for changes only affecting Bazel rules:
```
ci-exactly: linux_x64_bazel
```
Opt in to the Linux arm64 build:
```
ci-extra: linux_arm64_clang
```
Opt in to the MacOS build and test workflows:
```
ci-extra: macos_arm64_clang
```

Other opt in builds:

ci-extra: linux_x64_clang_byollvm, linux_x64_clang_debug, linux_x64_clang_tsan

For example, this PR opted in to running the build_test_all_windows job (which was renamed to windows_x64_msvc):

ci-extra

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

ci_enabled_jobs