[llvm] [llvm][docs] Reorder sections in GitHub.rst (PR #134212)
Andrzej Warzyński via llvm-commits
llvm-commits at lists.llvm.org
Thu Apr 3 07:39:49 PDT 2025
https://github.com/banach-space updated https://github.com/llvm/llvm-project/pull/134212
>From f930cd9e804fb9b4e94e621e2e5f2ae41a3cca36 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Thu, 3 Apr 2025 08:17:42 +0100
Subject: [PATCH 1/2] [llvm][docs] Reorder sections in GitHub.rst
Reorder sections in GitHub.rst so that "Branches" and "Stacked Pull
Requests" appear after the more general section on pull requests. This
improves the conceptual flow for readers new to the process:
New order:
* Introduction
* Before your first PR
* Pull Requests
* Branches
* Stacked Pull Requests
* Approvals
* Landing your change
* ...
Previous order:
* Introduction
* Before your first PR
* Branches
* Stacked Pull Requests
* Pull Requests
* Approvals
* Landing your change
* ...
This change only reorders existing text - no content edits.
---
llvm/docs/GitHub.rst | 199 ++++++++++++++++++++++---------------------
1 file changed, 100 insertions(+), 99 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index a235fa51a6473..752cdceb397ad 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -21,105 +21,6 @@ Before your first PR
Please ensure that you have set a valid email address in your GitHub account,
see :ref:`github-email-address`.
-.. _github_branches:
-
-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**.
-
-Stacked Pull Requests
-=====================
-
-To separate related changes or to break down a larger PR into smaller, reviewable
-pieces, use "stacked pull requests" — this helps make the review process
-smoother.
-
-.. note::
- The LLVM Project monorepo on GitHub is configured to always use "Squash and
- Merge" as the pull request merge option. As a result, each PR results in
- exactly one commit being merged into the project.
-
- This means that stacked pull requests are the only available option for
- landing a series of related changes. In contrast, submitting a PR with
- multiple commits and merging them as-is (without squashing) is not supported
- in LLVM.
-
-While GitHub does not natively support stacked pull requests, there are several
-common alternatives.
-
-To illustrate, assume that you are working on two branches in your fork of the
-``llvm/llvm-project`` repository, and you want to eventually merge both into
-``main``:
-
-- `feature_1`, which contains commit `feature_commit_1`
-- `feature_2`, which contains commit `feature_commit_2` and depends on
- `feature_1` (so it also includes `feature_commit_1`)
-
-Your options are as follows:
-
-#. Two PRs with a dependency note
-
- Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
- note in the PR summary indicating that it depends on PR_1 (e.g.,
- “Depends on #PR_1”).
-
- To make review easier, make it clear which commits are part of the base PR
- and which are new, e.g. "The first N commits are from the base PR". This
- helps reviewers focus only on the incremental changes.
-
-#. Use user branches in ``llvm/llvm-project``
-
- Create user branches in the main repository, as described
- :ref:`above<github_branches>`. Then:
-
- - Open a pull request from `users/<username>/feature_1` → `main`
- - Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
-
- This approach allows GitHub to display clean, incremental diffs for each PR
- in the stack, making it much easier for reviewers to see what has changed at
- each step. Once `feature_1` is merged, you can rebase and re-target
- `feature_2` to `main`.
-
-#. Use a stacked PR tool
-
- Use tools like SPR or Graphite (described below) to automate managing
- stacked PRs. These tools are also based on using user branches
- in ``llvm/llvm-project``.
-
-.. note::
- When not using user branches, GitHub will not display proper diffs for
- subsequent PRs in a stack. Instead, it will show a combined diff that
- includes all commits from earlier PRs.
-
- As described in the first option above, in such cases it is the PR author’s
- responsibility to clearly indicate which commits are relevant to the
- current PR. For example: “The first N commits are from the base PR.”
-
- You can avoid this issue by using user branches directly in the
- ``llvm/llvm-project`` repository.
-
-
-Using Graphite for stacked Pull Requests
-----------------------------------------
-
-`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
-by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
-
-Graphite will want to create branches under ``llvm/llvm-project`` rather than your
-private fork, so the guidance above, about branch naming, is critical, otherwise
-``gt submit`` (i.e. publish your PRs for review) will fail.
-
-Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
-Include the last ``/``.
-
-If you didn't do the above and Graphite created non-prefixed branches, a simple way to
-unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
-and ``gt track``.
-
Pull Requests
=============
The LLVM project is using GitHub Pull Requests for Code Reviews. This document
@@ -218,6 +119,106 @@ you won't encounter merge conflicts when landing the PR.
collaborating with others on a single branch, be careful how and when you push
changes. ``--force-with-lease`` may be useful in this situation.
+.. _github_branches:
+
+Branches
+========
+
+It is possible to create branches that start 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 above). User branches that
+aren't associated with a pull-request **will be deleted**.
+
+Stacked Pull Requests
+=====================
+
+To separate related changes or to break down a larger PR into smaller, reviewable
+pieces, use "stacked pull requests" — this helps make the review process
+smoother.
+
+.. note::
+ The LLVM Project monorepo on GitHub is configured to always use "Squash and
+ Merge" as the pull request merge option. As a result, each PR results in
+ exactly one commit being merged into the project.
+
+ This means that stacked pull requests are the only available option for
+ landing a series of related changes. In contrast, submitting a PR with
+ multiple commits and merging them as-is (without squashing) is not supported
+ in LLVM.
+
+While GitHub does not natively support stacked pull requests, there are several
+common alternatives.
+
+To illustrate, assume that you are working on two branches in your fork of the
+``llvm/llvm-project`` repository, and you want to eventually merge both into
+``main``:
+
+- `feature_1`, which contains commit `feature_commit_1`
+- `feature_2`, which contains commit `feature_commit_2` and depends on
+ `feature_1` (so it also includes `feature_commit_1`)
+
+Your options are as follows:
+
+#. Two PRs with a dependency note
+
+ Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
+ note in the PR summary indicating that it depends on PR_1 (e.g.,
+ “Depends on #PR_1”).
+
+ To make review easier, make it clear which commits are part of the base PR
+ and which are new, e.g. "The first N commits are from the base PR". This
+ helps reviewers focus only on the incremental changes.
+
+#. Use user branches in ``llvm/llvm-project``
+
+ Create user branches in the main repository, as described
+ :ref:`above<github_branches>`. Then:
+
+ - Open a pull request from `users/<username>/feature_1` → `main`
+ - Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
+
+ This approach allows GitHub to display clean, incremental diffs for each PR
+ in the stack, making it much easier for reviewers to see what has changed at
+ each step. Once `feature_1` is merged, you can rebase and re-target
+ `feature_2` to `main`.
+
+#. Use a stacked PR tool
+
+ Use tools like SPR or Graphite (described below) to automate managing
+ stacked PRs. These tools are also based on using user branches
+ in ``llvm/llvm-project``.
+
+.. note::
+ When not using user branches, GitHub will not display proper diffs for
+ subsequent PRs in a stack. Instead, it will show a combined diff that
+ includes all commits from earlier PRs.
+
+ As described in the first option above, in such cases it is the PR author’s
+ responsibility to clearly indicate which commits are relevant to the
+ current PR. For example: “The first N commits are from the base PR.”
+
+ You can avoid this issue by using user branches directly in the
+ ``llvm/llvm-project`` repository.
+
+
+Using Graphite for stacked Pull Requests
+----------------------------------------
+
+`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
+by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
+
+Graphite will want to create branches under ``llvm/llvm-project`` rather than your
+private fork, so the guidance above, about branch naming, is critical, otherwise
+``gt submit`` (i.e. publish your PRs for review) will fail.
+
+Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
+Include the last ``/``.
+
+If you didn't do the above and Graphite created non-prefixed branches, a simple way to
+unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
+and ``gt track``.
+
+
Approvals
---------
>From 78245a4a46db5b8bd6e972c0a0c0a61aafbf0980 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Thu, 3 Apr 2025 15:38:56 +0100
Subject: [PATCH 2/2] fixup! [llvm][docs] Reorder sections in GitHub.rst
Shuffle according to feedback from Martin, add ToC
---
llvm/docs/GitHub.rst | 187 ++++++++++++++++++++++---------------------
1 file changed, 94 insertions(+), 93 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 752cdceb397ad..faadf67c1bacf 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -4,6 +4,9 @@
LLVM GitHub User Guide
======================
+.. contents::
+ :local:
+
Introduction
============
The LLVM Project uses `GitHub <https://github.com/>`_ for
@@ -119,6 +122,97 @@ you won't encounter merge conflicts when landing the PR.
collaborating with others on a single branch, be careful how and when you push
changes. ``--force-with-lease`` may be useful in this situation.
+Approvals
+---------
+
+Before merging a PR you must have the required approvals. See
+:ref:`lgtm_how_a_patch_is_accepted` for more details.
+
+Landing your change
+-------------------
+
+After your PR is approved, ensure that:
+
+ * The PR title and description describe the final changes. These will be used
+ as the title and message of the final squashed commit. The titles and
+ messages of commits in the PR will **not** be used.
+ * You have set a valid email address in your GitHub account, see :ref:`github-email-address`.
+
+.. note::
+ The LLVM Project monorepo on GitHub is configured to always use "Squash
+ and Merge" as the pull request merge option when using the web interface.
+ With this option, GitHub uses the PR summary as the default commit
+ message.
+
+ Users with write access who can merge PRs have a final opportunity to edit
+ the commit title and message before merging. However, this option is not
+ available to contributors without write access.
+
+At this point, you can merge your changes. If you do not have write permissions
+for the repository, the merge button in GitHub's web interface will be
+disabled. If this is the case, continue following the steps here but ask one of
+your reviewers to click the merge button on your behalf.
+
+If the PR is a single commit, all you need to do is click the merge button in
+GitHub's web interface.
+
+If your PR contains multiple commits, you need to consolidate those commits into
+one commit. There are three different ways to do this, shown here with the most
+commonly used first:
+
+* 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.
+
+* `Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
+ with fixups. This is the recommended method since you can control the final
+ commit message and check 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 in GitHub's web interface afterwards.
+
+* Merge using the GitHub command line interface. Switch 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 --force
+ 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.
+
.. _github_branches:
Branches
@@ -218,99 +312,6 @@ If you didn't do the above and Graphite created non-prefixed branches, a simple
unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
and ``gt track``.
-
-Approvals
----------
-
-Before merging a PR you must have the required approvals. See
-:ref:`lgtm_how_a_patch_is_accepted` for more details.
-
-
-Landing your change
--------------------
-
-After your PR is approved, ensure that:
-
- * The PR title and description describe the final changes. These will be used
- as the title and message of the final squashed commit. The titles and
- messages of commits in the PR will **not** be used.
- * You have set a valid email address in your GitHub account, see :ref:`github-email-address`.
-
-.. note::
- The LLVM Project monorepo on GitHub is configured to always use "Squash
- and Merge" as the pull request merge option when using the web interface.
- With this option, GitHub uses the PR summary as the default commit
- message.
-
- Users with write access who can merge PRs have a final opportunity to edit
- the commit title and message before merging. However, this option is not
- available to contributors without write access.
-
-At this point, you can merge your changes. If you do not have write permissions
-for the repository, the merge button in GitHub's web interface will be
-disabled. If this is the case, continue following the steps here but ask one of
-your reviewers to click the merge button on your behalf.
-
-If the PR is a single commit, all you need to do is click the merge button in
-GitHub's web interface.
-
-If your PR contains multiple commits, you need to consolidate those commits into
-one commit. There are three different ways to do this, shown here with the most
-commonly used first:
-
-* 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.
-
-* `Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
- with fixups. This is the recommended method since you can control the final
- commit message and check 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 in GitHub's web interface afterwards.
-
-* Merge using the GitHub command line interface. Switch 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 --force
- 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.
-
Pre-merge Continuous Integration (CI)
-------------------------------------
More information about the llvm-commits
mailing list