From be8759dff108486851a5e1972499c7849833624b Mon Sep 17 00:00:00 2001 From: Andrzej Warzynski Date: Fri, 21 Mar 2025 16:58:14 +0000 Subject: [PATCH 1/4] [docs][GitHub] Document alternative approach to stacked PRs --- llvm/docs/GitHub.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst index 03cf2251f955e..8b87e47bda2a8 100644 --- a/llvm/docs/GitHub.rst +++ b/llvm/docs/GitHub.rst @@ -29,8 +29,23 @@ intended to be able to support "stacked" pull-request. Do not create any branche 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 +===================== + +GitHub does not natively support stacked pull requests. There are two common +alternatives: + + * Add a note in your PR summary indicating that your patch is part of a + series or depends on another PR (e.g., “Depends on #123456”). It also helps + to highlight which commits belong to other PRs, so reviewers can focus only + on the relevant changes. + * Use Graphite (described below), a tool that supports stacked PR workflows. + +Both approaches help streamline the review process. Choose the one that works +best for you. + Using Graphite for stacked Pull Requests -======================================== +---------------------------------------- `Graphite `_ is a stacked pull request tool supported by the LLVM repo (the other being `reviewable.io `_). From ba20d0566388c54856e2e078912823fb057ebcec Mon Sep 17 00:00:00 2001 From: Andrzej Warzynski Date: Sat, 22 Mar 2025 19:54:29 +0000 Subject: [PATCH 2/4] fixup! [docs][GitHub] Document alternative approach to stacked PRs Expand + add a note on SPR --- llvm/docs/GitHub.rst | 45 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst index 8b87e47bda2a8..09dc7c16a9c38 100644 --- a/llvm/docs/GitHub.rst +++ b/llvm/docs/GitHub.rst @@ -21,6 +21,8 @@ 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 ======== @@ -32,17 +34,42 @@ aren't associated with a pull-request **will be deleted**. Stacked Pull Requests ===================== -GitHub does not natively support stacked pull requests. There are two common -alternatives: +GitHub does not natively support stacked pull requests. However, there are +several common alternatives. + +To illustrate, let's assume you're 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 dependency note + + Create PR_1 for branch feature_1 and PR_2 for branch feature_2. In PR_2, add a + note in the PR summary indicating that it is part of a series or depends on + another PR (e.g., “Depends on #PR_1”). It's also helpful to highlight which + commits belong to the base PR, so reviewers can focus on the new changes. + +#. User branches in `llvm/llvm-project` + + Create user branches in the main repository, as described + :ref:`above`. Then: + + * Create a pull request from `users//feature_1` → `main` + * Create another from `users//feature_2` → + `users//feature_1` Once `feature_1` is merged, you can update the + base of the second PR to target main. + +#. Use a stacked PR tool - * Add a note in your PR summary indicating that your patch is part of a - series or depends on another PR (e.g., “Depends on #123456”). It also helps - to highlight which commits belong to other PRs, so reviewers can focus only - on the relevant changes. - * Use Graphite (described below), a tool that supports stacked PR workflows. + Use a tool like SPR or Graphite (described below) to manage stacked PRs more + easily. -Both approaches help streamline the review process. Choose the one that works -best for you. +Each of these approaches can help streamline the review process. Choose the one +that works best for your workflow. Using Graphite for stacked Pull Requests ---------------------------------------- From 41d32b71ea39b12a7c8bd5bd28ecf32c0089d29f Mon Sep 17 00:00:00 2001 From: Andrzej Warzynski Date: Tue, 25 Mar 2025 14:05:52 +0000 Subject: [PATCH 3/4] fixup! fixup! [docs][GitHub] Document alternative approach to stacked PRs Address comments from Alex and Mehdi --- llvm/docs/GitHub.rst | 63 ++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst index 09dc7c16a9c38..721a899a49808 100644 --- a/llvm/docs/GitHub.rst +++ b/llvm/docs/GitHub.rst @@ -34,42 +34,59 @@ aren't associated with a pull-request **will be deleted**. Stacked Pull Requests ===================== -GitHub does not natively support stacked pull requests. However, there are -several common alternatives. +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. While GitHub does not natively support stacked pull requests, there +are several common alternatives. -To illustrate, let's assume you're working on two branches in your fork of the -``llvm/llvm-project`` repository, and you want to eventually merge both into ``main``: +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`). +- `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 dependency note +#. Two PRs with a dependency note - Create PR_1 for branch feature_1 and PR_2 for branch feature_2. In PR_2, add a - note in the PR summary indicating that it is part of a series or depends on - another PR (e.g., “Depends on #PR_1”). It's also helpful to highlight which - commits belong to the base PR, so reviewers can focus on the new changes. + 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”). -#. User branches in `llvm/llvm-project` + To make review easier, clearly highlight which commits are part of the base + PR and which are new. This helps reviewers focus only on the incremental + changes. - Create user branches in the main repository, as described - :ref:`above`. Then: +#. Use user branches in ``llvm/llvm-project`` - * Create a pull request from `users//feature_1` → `main` - * Create another from `users//feature_2` → - `users//feature_1` Once `feature_1` is merged, you can update the - base of the second PR to target main. + Create user branches in the main repository, as described + :ref:`above`. Then: + + - Open a pull request from `users//feature_1` → `main` + - Open another from `users//feature_2` → `users//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’s 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 a tool like SPR or Graphite (described below) to manage stacked PRs more - easily. + 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:: + Without using user branches, GitHub will not display a proper diff for + subsequent PRs in the stack. Instead, it will show a combined diff that + includes all commits in the stack. It is the PR author’s responsibility to + make it clear which commits are relevant to the current PR. + + You can avoid this issue by using user branches directly in the + ``llvm/llvm-project`` repository. -Each of these approaches can help streamline the review process. Choose the one -that works best for your workflow. Using Graphite for stacked Pull Requests ---------------------------------------- From 5591fe075a182fe2ea977361ddcb373face86289 Mon Sep 17 00:00:00 2001 From: Andrzej Warzynski Date: Wed, 26 Mar 2025 14:22:14 +0000 Subject: [PATCH 4/4] fixup! fixup! fixup! [docs][GitHub] Document alternative approach to stacked PRs Address comments from David, Martin and Simon. --- llvm/docs/GitHub.rst | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst index 721a899a49808..a235fa51a6473 100644 --- a/llvm/docs/GitHub.rst +++ b/llvm/docs/GitHub.rst @@ -36,8 +36,20 @@ 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. While GitHub does not natively support stacked pull requests, there -are several common alternatives. +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 @@ -55,9 +67,9 @@ Your options are as follows: note in the PR summary indicating that it depends on PR_1 (e.g., “Depends on #PR_1”). - To make review easier, clearly highlight which commits are part of the base - PR and which are new. This helps reviewers focus only on the incremental - changes. + 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`` @@ -68,8 +80,8 @@ Your options are as follows: - Open another from `users//feature_2` → `users//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’s changed - at each step. Once `feature_1` is merged, you can rebase and re-target + 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 @@ -79,10 +91,13 @@ Your options are as follows: in ``llvm/llvm-project``. .. note:: - Without using user branches, GitHub will not display a proper diff for - subsequent PRs in the stack. Instead, it will show a combined diff that - includes all commits in the stack. It is the PR author’s responsibility to - make it clear which commits are relevant to the current PR. + 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.