Contributing to HEIR

There are several ways to contribute to HEIR, including:

Ways to contribute

We welcome pull requests, and have tagged issues for newcomers:

For new proposals, please open a GitHub issue or start a discussion for feedback.

Contributing to code using pull requests

Preparing a pull request

The following steps should look familiar to typical workflows for pull request contributions. Feel free to consult GitHub Help if you need more information using pull requests. HEIR-specific processes begin at the pull request review stage.

  1. Sign the Contributor License Agreement (CLA). See more here.

  2. Fork the HEIR repository by clicking the Fork button on the repository page. This creates a copy of the HEIR repository on your own GitHub account.

  3. See Getting Started to install developer dependencies to build and run tests.

  4. Add the HEIR repository as an upstream remote, so you can sync your changes against it.

    git remote add upstream https://www.github.com/google/heir
    
  5. Create a development branch for your change:

     git checkout -b name-of-change
    

    And implement your changes using your favorite IDE. See IDE Configuration for more.

  6. Check HEIR’s lint and style checks by running the following from the top of the repository:

     pre-commit run --all
    
  7. Make sure tests are passing with the following:

     bazel test @heir//...
    
  8. Once you are ready with your change, create a commit as follows.

    git add change.cpp
    git commit -m "Detailed commit message"
    git push --set-upstream origin name-of-change
    

Pull request review flow

  1. New PR:
  • When a new PR is submitted, it is inspected for quality requirements, such as the CLA requirement, and a sufficient PR description.
  • If the PR passes checks, we assign a reviewer. If not, we request additional changes to ensure the PR passes CI checks.
  1. Review
  • A reviewer will check the PR and potentially request additional changes.
  • If a change is needed, the contributor is requested to make a suggested change. Please make changes with additional commits to your PR, to ensure that the reviewer can easily see the diff.
  • If all looks good, the reviewer will approve the PR.
  • This cycle repeats itself until the PR is approved.
  1. Approved
  • At this stage, you must squash your commits into a single commit.
  • Once the PR is approved, a GitHub workflow will check your PR for multiple commits. You may use the git rebase -i to squash the commits. Pull requests must comprise of a single git commit before merging.
  1. Pull Ready
  • Once the PR is squashed into a single git commit, a maintainer will apply the pull ready label.
  • This initiates the internal code migration and presubmits.
  • If needed, we may come to you to make some minor changes in case tests fail at this stage. If so, we will request changes from the GitHub UI and the PR must be approved again.
  • At times, it may not be your change, but it may be additional internal lints and layering checks that are not integrated with bazel or open-source tooling. We will go ahead and fix this.
  • Once the internal tests pass, we merge the code internally and externally. You will see copybara-bot close the PR and merge your commit directly into main.