Contributing to IREElink
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 policieslink
Code of conductlink
This project follows the OpenXLA Code of Conduct.
Developer Certificate of Originlink
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:
-
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
-
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
-
The contribution was provided directly to me by some other person who certified 1., 2. or 3. and I have not modified it.
-
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. This
requires that all commits included in pull requests include a Signed-off-by
line:
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. -
For more information about DCO enforcement and git workflows, see the dcoapp/app repository.
Contributor License Agreementlink
CLA is being replaced with DCO. Both are enabled while we migrate.
Contributions to this project must be accompanied by a Contributor License Agreement (CLA). Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.
- You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.
- You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
AUTHORS, CODEOWNERS, and MAINTAINERSlink
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 policieslink
Coding style guidelineslink
Most of the code style is derived from the Google Style Guides for the appropriate language and is generally not something we accept changes on (as clang-format and other linters set that for us). The C++ compiler portion of the project follows the MLIR/LLVM style guide.
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.
Tip - code formatters and lint scripts
Formatters like
clang-format
(C/C++) and
Black (Python) can be set to
run automatically in your editor of choice.
The script at
build_tools/scripts/lint.sh
can also be used to run the full suite of lint checks.
Testing policylink
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 policieslink
Code reviewslink
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 workflowslink
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 changeslink
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 accesslink
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.
Note: other GitHub organizations
Work on IREE sometimes spans other GitHub organizations like shark-infra. Reach out to a project member if you would also like access to repositories in those organizations.
Branch naminglink
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 contributorslink
Tool recommendationslink
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 systemslink
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)link
IREE uses GitHub Actions for CI. The primary CI is configured in the ci.yml workflow file.
Self-hosted runnerslink
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 scripting is checked in to this repository (see the README for that directory).
CI behavior manipulationlink
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 recipeslink
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: