Contributor Tips

This is an opinionated guide documenting workflows that some members of the team have found useful. It is focused on meta-tooling, not on IREE code specifically (you will find the latter in the Developer Overview). It is certainly possible to use workflows other than these, but some common tasks, especially for maintainers will likely be made easier if you use these flows. It assumes a basic knowledge of git and GitHub and suggests some specific ways of using it.

Git Structure

We tend to use the “triangular” or “forking” workflow. Develop primarily on a clone of the repository on your development machine. Any local branches named the same as persistent branches from the main repository (currently main and stable) are pristine (though potentially stale) copies. You only fastforward these to match upstream and otherwise do development on other branches. When sending PRs, you push to a different branch on your public fork and create the PR from there.

Setup

  1. Create a fork of the main repository.

  2. Create a local git repository with remotes upstream (the main repository) and origin (your personal fork). To list your current remotes git remote -v.

    a. If you already cloned from the main repository (e.g. by following the getting started guide):

    # From your existing git repo
$ git remote rename origin upstream
$ git remote add origin https://github.com/<github_username>/iree.git

    b. If you haven't already cloned:

    # From whatever directory under which you want to nest your repo
$ git clone https://github.com/<github_username>/iree.git
$ cd iree
$ git remote add upstream https://github.com/openxla/iree.git

    This is especially important for maintainers who have write access (so can push directly to the main repository) and admins who have elevated privileges (so can push directly to protected branches). These names are just suggestions, but you might find some scripts where the defaults are for remotes named like this. For extra safety, you can make it difficult to push directly to upstream by setting the push url to something invalid: git remote set-url --push upstream DISABLE, which requires re-enabling the push URL explicitly before pushing. You can wrap this behavior in a custom git command like git-sudo.

  3. Use a script like git_update.sh to easily synchronize main with upstream. Submodules make this is a little trickier than it should be. You can also turn this into a git command by adding it to your path as git-update.

Git Config

These are some additional options you could put in your top-level .gitconfig or repository-specific .git/config files that are conducive the recommended workflow

[push]
  default = current
[alias]
  # Delete branches that you pushed and have been deleted upstream, e.g. because
  # the PR was merged.
  gone = ! "git fetch -p  && git for-each-ref --format '%(refname:short) %(upstream:track)' | awk '$2 == \"[gone]\" {print $1}' | xargs -r git branch -D"
  # Update from upstream (custom command) and delete obsolete local branches.
  sync = ! (git update main && git gone)
  # Create a new branch based off of main (requires a clean working directory).
  new = "!f(){ \\\ngit checkout main && git switch -c $1; \\\n}; f"
  # Display branches in a useful "latest last" format
  br = for-each-ref --sort=committerdate refs/heads/ --format='%(HEAD) %(color:yellow)%(refname:short)%(color:reset) - %(color:red)%(objectname:short)%(color:reset) - %(contents:subject) (%(color:green)%(committerdate:relative)%(color:reset))'
  # `git git foo` -> `git foo` typo fixer
  git = "!f(){ \\\n git \"$@\"; \\\n}; f"
  # Get the git root directory
  root = rev-parse --show-toplevel
  # checkout, but also sync submodules
  ch = "!f() { \\\n git checkout \"$@\"; git submodule sync && git submodule update --init; \\\n}; f"
  # See the diff for a PR branch vs the main branch
  diffmain = diff --merge-base main
  # See only the files that differ vs the main branch
  whatsout = diffmain --name-only
[checkout]
  # If the checkout command
  defaultRemote = origin
[pull]
  # When pulling, only complete the pull if its a clean fast forward.
  ff = only
[remote]
  # Push to your fork (origin) by default
  pushDefault = origin
[url "ssh://git@github.com/"]
  # Pull with https (so no auth required), but push with ssh.
  pushInsteadOf = https://github.com/

Useful Tools