Development workflow

This page describes the day-to-day mechanics of producing a change against llvm/llvm-project.

Set up

1. Fork github.com/llvm/llvm-project on GitHub.

2. Clone your fork. Add the upstream remote:

   git clone git@github.com:<you>/llvm-project.git
   cd llvm-project
   git remote add upstream https://github.com/llvm/llvm-project.git

3. Configure git as the project expects:

   git config user.email "<your real email>"
   git config user.name  "<your real name>"

   The project uses real names; pseudonyms are not accepted in From: headers.

4. Build at least the affected subprojects. See getting started. For an iterative loop, build with -DLLVM_ENABLE_ASSERTIONS=ON; the assertions catch a huge fraction of pass and codegen bugs.

Branching

Branch off the latest main:

git checkout main
git pull --rebase upstream main
git checkout -b <area>/<short-description>

Branch names are not enforced, but most contributors use <area>/<short-description> (e.g., instcombine/fold-and-of-icmp).

The edit – build – test loop

A typical inner loop:

# edit
$EDITOR llvm/lib/Transforms/InstCombine/...

# rebuild only what's needed (Ninja is incremental and fast)
ninja -C build opt

# run the targeted tests
build/bin/llvm-lit -v llvm/test/Transforms/InstCombine/

# narrow further if a single file fails
build/bin/llvm-lit -v llvm/test/Transforms/InstCombine/and-icmp.ll

Then before pushing, run the full suite for the affected subproject:

ninja -C build check-llvm

Run check-clang, check-mlir, check-lld, etc. as appropriate. CI will run more of them — but local checks save round-trips.

Commit messages

LLVM uses a tightly conventional commit-message format:

[Area][Subarea] One-line summary in the imperative mood

Optional body explaining the rationale and the user-visible effect.
Wrap at 72 columns.

Fixes: #12345

Examples drawn from recent history:

[CIR] Fix unused variable warning (#195130)
[InstCombine] Avoid useless cast in fold of (X >> Y) << Y (#194321)
[clang][CodeGen] Add support for __builtin_X (#194099)

Common area prefixes:

• LLVM: [InstCombine], [CodeGen], [X86], [AArch64], [GlobalISel], [LTO], [Object], [MC], [ADT], [Support], [ORC], ...
• Clang: [clang], [clang][CodeGen], [clang][Sema], [clang][Driver], [clang][Modules], ...
• Other: [lld], [lldb], [mlir], [flang], [bolt], [libc++], [libc], [compiler-rt], [openmp], ...

Pull requests

Push your branch and open a PR against llvm/llvm-project:main. For PR conventions:

• The PR description should mirror the commit body. Include reproducer instructions if you fixed a bug.
• For multi-commit PRs, prefer to keep commits logically separable rather than amending into a single commit. Reviewers can read commit-by-commit.
• Mark draft PRs as draft until you want review.
• Tag the area's maintainer (see the per-subproject Maintainers.md) if your PR has been quiet for several days.

Landing changes

LLVM uses two landing strategies:

• Squash and merge via the GitHub UI for most PRs. The PR title becomes the commit subject; pay attention to the title format described above.
• Manual stacked landings via git push origin HEAD:main for contributors with commit access who are landing a chain of dependent commits. This bypasses GitHub's squash and is appropriate when each commit is independently reviewable.

Reverts and bisecting

If a change breaks the buildbots or a downstream user, the project culture prefers a fast revert ("revert and discuss") over keeping a broken tree green by force. A revert PR can be opened against main with the original commit's hash in the message:

Revert "[InstCombine] Avoid useless cast ..." (#194321)

This commit broke the AArch64 buildbot ...

Bisecting is a normal debugging step. With Ninja and a release build, a bisect over a few hundred commits is typically a half-hour task.

Backporting to release branches

Bug fixes for the upcoming release branch (release/N.x) follow a separate process: file a backport request via GitHub and a release manager will cherry-pick. See the release process documentation.