There are too many articles on how to use Git, so go Google it if you don’t know how to do the following:
- Creating a commit in a repository
- Create / Delete / Switch between branches
- Rebase a branch to another
- Revert a commit
- The difference between “Squash and merge” and “Rebase and merge”
In the context of LLVM upstream development, the term “patch” refers to a “revision” that will later be committed to upstream when it is accepted. You will be submitting a commit by creating a revision to the Phabricator. Here is an example of how a revision looks like: https://reviews.llvm.org/D99323.
LLVM’s patch review website is based on Phabricator, you can find it on https://reviews.llvm.org/.
Arcanist is a command-line interface for Phabricator. You can find how to download it in the link. Other than that, you may encounter certificate issues, you can resolve with the instructions mentioned here(https://reviews.llvm.org/D110976).
LLVM’s revision is different from GitHub’s pull request. GitHub’s pull request can contain multiple commits, while LLVM’s revision can only contain 1 commit. So if you have multiple commits, you either squash it into one commits or create multiple revision.
Here are some commands I frequently use, feel free to help me update this document.
arc diff: This command generates a “differential” (aka revision) of the local change. A revision will belong to a patch. You can later commit the revision when it is accepted by other reviewers.
arc diff --create: Create a revision upon local change
- After the command, Arcanist will bring you to your local editor to jot down commit messages
arc diff --update [REVISION_ID]: Update a revision upon local change
- You may use this when reviewers ask for you to rebase the current revision upon the latest main.
arc patch [REVISION_ID]: Grep a certain online revision to your local Git.
- You may use this when you want to continue a patch you have been working on.
- The patch may be old compared to the latest main, and you may have to recompile many things when you switch to an older commit.
- Update commit messages, it adds reviewers name into the commit when it is accepted.
arc set-config editor vim
- If your default editor is not vim
Ask your reviewer to commit your 1st commit
At least for myself, I was told that usually the 1st commit of a new contributor will be committed by the reviewer that already has commit access to the upstream repository. So you may kindly ask the reviewer to do it for you.
After that you may want commit access of your own since you are actively part of the community right now! You can request for commit access from Mr. Lattner by sending him an email. I believe after you have done the 1st commit you must be able to find his email link, so I will not expose it here 😉.
Make sure you can be online and revert your patch when you commit it
In case you break the build, make sure you are able to stay around for an hour or two after your commit before you do it. You will be spammed with mail-bots of failure notifications if you really did break the build.
Subscribe to mailing list
You may want to subscribe to the LLVM mailing list and LLVM Weekly to keep yourself up-to-date on some upstream development.
Some LLVM documents you might find helpful: