mirror of
https://github.com/capstone-engine/llvm-capstone.git
synced 2025-02-24 20:44:09 +00:00
384 lines
13 KiB
ReStructuredText
384 lines
13 KiB
ReStructuredText
.. _github-reviews:
|
|
|
|
======================
|
|
LLVM GitHub User Guide
|
|
======================
|
|
|
|
Introduction
|
|
============
|
|
The LLVM Project uses `GitHub <https://github.com/>`_ for
|
|
`Source Code <https://github.com/llvm/llvm-project>`_,
|
|
`Releases <https://github.com/llvm/llvm-project/releases>`_,
|
|
`Issue Tracking <https://github.com/llvm/llvm-project/issues>`_., and
|
|
`Code Reviews <https://github.com/llvm/llvm-project/pulls>`_.
|
|
|
|
This page describes how the LLVM Project users and developers can
|
|
participate in the project using GitHub.
|
|
|
|
Branches
|
|
========
|
|
|
|
It is possible to create branches that starts with `users/<username>/`, however this is
|
|
intended to be able to support "stacked" pull-request. Do not create any branches in the
|
|
llvm/llvm-project repository otherwise, please use a fork (see below). User branches that
|
|
aren't associated with a pull-request **will be deleted**.
|
|
|
|
Pull Requests
|
|
=============
|
|
The LLVM project is using GitHub Pull Requests for Code Reviews. This document
|
|
describes the typical workflow of creating a Pull Request and getting it reviewed
|
|
and accepted. This is meant as an overview of the GitHub workflow, for complete
|
|
documentation refer to `GitHub's documentation <https://docs.github.com/pull-requests>`_.
|
|
|
|
GitHub Tools
|
|
------------
|
|
You can interact with GitHub in several ways: via git command line tools,
|
|
the web browser, `GitHub Desktop <https://desktop.github.com/>`_, or the
|
|
`GitHub CLI <https://cli.github.com>`_. This guide will cover the git command line
|
|
tools and the GitHub CLI. The GitHub CLI (`gh`) will be most like the `arc` workflow and
|
|
recommended.
|
|
|
|
Creating Pull Requests
|
|
----------------------
|
|
Keep in mind that when creating a pull request, it should generally only contain one
|
|
self-contained commit initially.
|
|
This makes it easier for reviewers to understand the introduced changes and
|
|
provide feedback. It also helps maintain a clear and organized commit history
|
|
for the project. If you have multiple changes you want to introduce, it's
|
|
recommended to create separate pull requests for each change.
|
|
|
|
Create a local branch per commit you want to submit and then push that branch
|
|
to your `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks>`_
|
|
of the llvm-project and
|
|
`create a pull request from the fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
|
|
As GitHub uses the first line of the commit message truncated to 72 characters
|
|
as the pull request title, you may have to edit to reword or to undo this
|
|
truncation.
|
|
|
|
Creating Pull Requests with GitHub CLI
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
With the CLI it's enough to create the branch locally and then run:
|
|
|
|
::
|
|
|
|
gh pr create
|
|
|
|
When prompted select to create and use your own fork and follow
|
|
the instructions to add more information needed.
|
|
|
|
.. note::
|
|
|
|
When you let the GitHub CLI create a fork of llvm-project to
|
|
your user, it will change the git "remotes" so that "origin" points
|
|
to your fork and "upstream" points to the main llvm-project repository.
|
|
|
|
Updating Pull Requests
|
|
----------------------
|
|
In order to update your pull request, the only thing you need to do is to push
|
|
your new commits to the branch in your fork. That will automatically update
|
|
the pull request.
|
|
|
|
When updating a pull request, you should push additional "fix up" commits to
|
|
your branch instead of force pushing. This makes it easier for GitHub to
|
|
track the context of previous review comments. Consider using the
|
|
`built-in support for fixups <https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt>`_
|
|
in git.
|
|
|
|
If you do this, you must squash and merge before landing the PR and
|
|
you must use the pull request title and description as the commit message.
|
|
You can do this manually with an interactive git rebase or with GitHub's
|
|
built-in tool. See the section about landing your fix below.
|
|
|
|
When pushing to your branch, make sure you push to the correct fork. Check your
|
|
remotes with:
|
|
|
|
::
|
|
|
|
git remote -v
|
|
|
|
And make sure you push to the remote that's pointing to your fork.
|
|
|
|
Rebasing Pull Requests and Force Pushes
|
|
---------------------------------------
|
|
In general, you should avoid rebasing a Pull Request and force pushing to the
|
|
branch that's the root of the Pull Request during the review. This action will
|
|
make the context of the old changes and comments harder to find and read.
|
|
|
|
Sometimes, a rebase might be needed to update your branch with a fix for a test
|
|
or in some dependent code.
|
|
|
|
After your PR is reviewed and accepted, you want to rebase your branch to ensure
|
|
you won't encounter merge conflicts when landing the PR.
|
|
|
|
Landing your change
|
|
-------------------
|
|
When your PR has been accepted you can use the web interface to land your change.
|
|
If you have created multiple commits to address feedback at this point you need
|
|
to consolidate those commits into one commit. There are two different ways to
|
|
do this:
|
|
|
|
`Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
|
|
with fixup's. This is the recommended method since you can control the final
|
|
commit message and inspect that the final commit looks as you expect. When
|
|
your local state is correct, remember to force-push to your branch and press
|
|
the merge button afterwards.
|
|
|
|
Use the button `Squash and merge` in GitHub's web interface, if you do this
|
|
remember to review the commit message when prompted.
|
|
|
|
Afterwards you can select the option `Delete branch` to delete the branch
|
|
from your fork.
|
|
|
|
You can also merge via the CLI by switching to your branch locally and run:
|
|
|
|
::
|
|
|
|
gh pr merge --squash --delete-branch
|
|
|
|
If you observe an error message from the above informing you that your pull
|
|
request is not mergeable, then that is likely because upstream has been
|
|
modified since your pull request was authored in a way that now results in a
|
|
merge conflict. You must first resolve this merge conflict in order to merge
|
|
your pull request. In order to do that:
|
|
|
|
::
|
|
|
|
git fetch upstream
|
|
git rebase upstream/main
|
|
|
|
Then fix the source files causing merge conflicts and make sure to rebuild and
|
|
retest the result. Then:
|
|
|
|
::
|
|
|
|
git add <files with resolved merge conflicts>
|
|
git rebase --continue
|
|
|
|
Finally, you'll need to force push to your branch one more time before you can
|
|
merge:
|
|
|
|
::
|
|
|
|
git push -f
|
|
gh pr merge --squash --delete-branch
|
|
|
|
This force push may ask if you intend to push hundreds, or potentially
|
|
thousands of patches (depending on how long it's been since your pull request
|
|
was initially authored vs. when you intended to merge it). Since you're pushing
|
|
to a branch in your fork, this is ok and expected. Github's UI for the pull
|
|
request will understand that you're rebasing just your patches, and display
|
|
this result correctly with a note that a force push did occur.
|
|
|
|
|
|
Checking out another PR locally
|
|
-------------------------------
|
|
Sometimes you want to review another person's PR on your local machine to run
|
|
tests or inspect code in your preferred editor. This is easily done with the
|
|
CLI:
|
|
|
|
::
|
|
|
|
gh pr checkout <PR Number>
|
|
|
|
This is also possible with the web interface and the normal git command line
|
|
tools, but the process is a bit more complicated. See GitHub's
|
|
`documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally?platform=linux&tool=webui#modifying-an-inactive-pull-request-locally>`_
|
|
on the topic.
|
|
|
|
Example Pull Request with GitHub CLI
|
|
====================================
|
|
Here is an example for creating a Pull Request with the GitHub CLI:
|
|
|
|
::
|
|
|
|
# Clone the repo
|
|
gh repo clone llvm/llvm-project
|
|
|
|
# Switch to the repo and create a new branch
|
|
cd llvm-project
|
|
git switch -c my_change
|
|
|
|
# Create your changes
|
|
$EDITOR file.cpp
|
|
|
|
# Don't forget clang-format
|
|
git clang-format
|
|
|
|
# and don't forget running your tests
|
|
ninja check-llvm
|
|
|
|
# Commit, use a good commit message
|
|
git commit file.cpp
|
|
|
|
# Create the PR, select to use your own fork when prompted.
|
|
# If you don't have a fork, gh will create one for you.
|
|
gh pr create
|
|
|
|
# If you get any review comments, come back to the branch and
|
|
# adjust them.
|
|
git switch my_change
|
|
$EDITOR file.cpp
|
|
|
|
# Commit your changes
|
|
git commit file.cpp -m "Code Review adjustments"
|
|
|
|
# Format changes
|
|
git clang-format HEAD~
|
|
|
|
# Recommit if any formatting changes
|
|
git commit -a --amend
|
|
|
|
# Push your changes to your fork branch, be mindful of
|
|
# your remotes here, if you don't remember what points to your
|
|
# fork, use git remote -v to see. Usually origin points to your
|
|
# fork and upstream to llvm/llvm-project
|
|
git push origin my_change
|
|
|
|
Before merging the PR, it is recommended that you rebase locally and re-run test
|
|
checks:
|
|
|
|
::
|
|
|
|
# Add upstream as a remote (if you don't have it already)
|
|
git remote add upstream https://github.com/llvm/llvm-project.git
|
|
|
|
# Make sure you have all the latest changes
|
|
git fetch upstream && git rebase -i upstream/main
|
|
|
|
# Make sure tests pass with latest changes and your change
|
|
ninja check
|
|
|
|
# Push the rebased changes to your fork.
|
|
git push origin my_change -f
|
|
|
|
# Now merge it
|
|
gh pr merge --squash --delete-branch
|
|
|
|
|
|
See more in-depth information about how to contribute in the following documentation:
|
|
|
|
* :doc:`Contributing`
|
|
* :doc:`MyFirstTypoFix`
|
|
|
|
Example Pull Request with git
|
|
====================================
|
|
|
|
Instead of using the GitHub CLI to create a PR, you can push your code to a
|
|
remote branch on your fork and create the PR to upstream using the GitHub web
|
|
interface.
|
|
|
|
Here is an example of making a PR using git and the GitHub web interface:
|
|
|
|
First follow the instructions to [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository).
|
|
|
|
Next follow the instructions to [clone your forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository).
|
|
|
|
Once you've cloned your forked repository,
|
|
|
|
::
|
|
|
|
# Switch to the forked repo
|
|
cd llvm-project
|
|
|
|
# Create a new branch
|
|
git switch -c my_change
|
|
|
|
# Create your changes
|
|
$EDITOR file.cpp
|
|
|
|
# Don't forget clang-format
|
|
git clang-format
|
|
|
|
# and don't forget running your tests
|
|
ninja check-llvm
|
|
|
|
# Commit, use a good commit message
|
|
git commit file.cpp
|
|
|
|
# Push your changes to your fork branch, be mindful of
|
|
# your remotes here, if you don't remember what points to your
|
|
# fork, use git remote -v to see. Usually origin points to your
|
|
# fork and upstream to llvm/llvm-project
|
|
git push origin my_change
|
|
|
|
Navigate to the URL printed to the console from the git push command in the last step.
|
|
Create a pull request from your branch to llvm::main.
|
|
|
|
::
|
|
|
|
# If you get any review comments, come back to the branch and
|
|
# adjust them.
|
|
git switch my_change
|
|
$EDITOR file.cpp
|
|
|
|
# Commit your changes
|
|
git commit file.cpp -m "Code Review adjustments"
|
|
|
|
# Format changes
|
|
git clang-format HEAD~
|
|
|
|
# Recommit if any formatting changes
|
|
git commit -a --amend
|
|
|
|
# Re-run tests and make sure nothing broke.
|
|
ninja check
|
|
|
|
# Push your changes to your fork branch, be mindful of
|
|
# your remotes here, if you don't remember what points to your
|
|
# fork, use git remote -v to see. Usually origin points to your
|
|
# fork and upstream to llvm/llvm-project
|
|
git push origin my_change
|
|
|
|
Before merging the PR, it is recommended that you rebase locally and re-run test
|
|
checks:
|
|
|
|
::
|
|
|
|
# Add upstream as a remote (if you don't have it already)
|
|
git remote add upstream https://github.com/llvm/llvm-project.git
|
|
|
|
# Make sure you have all the latest changes
|
|
git fetch upstream && git rebase -i upstream/main
|
|
|
|
# Make sure tests pass with latest changes and your change
|
|
ninja check
|
|
|
|
# Push the rebased changes to your fork.
|
|
git push origin my_change -f
|
|
|
|
Once your PR is approved, rebased, and tests are passing, click `Squash and
|
|
Merge` on your PR in the GitHub web interface.
|
|
|
|
See more in-depth information about how to contribute in the following documentation:
|
|
|
|
* :doc:`Contributing`
|
|
* :doc:`MyFirstTypoFix`
|
|
|
|
Releases
|
|
========
|
|
|
|
Backporting Fixes to the Release Branches
|
|
-----------------------------------------
|
|
You can use special comments on issues to make backport requests for the
|
|
release branches. This is done by making a comment containing one of the
|
|
following commands on any issue that has been added to one of the "X.Y.Z Release"
|
|
milestones.
|
|
|
|
::
|
|
|
|
/cherry-pick <commit> <commit> <...>
|
|
|
|
This command takes one or more git commit hashes as arguments and will attempt
|
|
to cherry-pick the commit(s) to the release branch. If the commit(s) fail to
|
|
apply cleanly, then a comment with a link to the failing job will be added to
|
|
the issue. If the commit(s) do apply cleanly, then a pull request will
|
|
be created with the specified commits.
|
|
|
|
::
|
|
|
|
/branch <owner>/<repo>/<branch>
|
|
|
|
This command will create a pull request against the latest release branch using
|
|
the <branch> from the <owner>/<repo> repository. <branch> cannot contain any
|
|
forward slash '/' characters.
|