[PATCH] D115519: [llvm][docs] Describe how to work with patch series on Phabricator

[David Spickett via Phabricator via llvm-commits]

DavidSpickett updated this revision to Diff 394860.
DavidSpickett added a comment.

". Where" -> ", where"


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D115519/new/

https://reviews.llvm.org/D115519

Files:
  llvm/docs/Phabricator.rst


Index: llvm/docs/Phabricator.rst
===================================================================
--- llvm/docs/Phabricator.rst
+++ llvm/docs/Phabricator.rst
@@ -128,6 +128,95 @@
 or llvm-commits, and if the subject line suggests the patch is something they
 should look at, they will.
 
+.. _creating-a-patch-series:
+
+Creating a patch series
+-----------------------
+
+Chaining reviews together requires some manual work. There are two ways to do it
+(these are also described `here <https://moz-conduit.readthedocs.io/en/latest/arcanist-user.html#series-of-commits>`_
+along with some screenshots of what to expect).
+
+.. _using-the-web-interface:
+
+Using the web interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This assumes that you've already created a Phabricator review for each commit,
+using `arc` or the web interface.
+
+* Go to what will be the last review in the series (the most recent).
+* Click "Edit Related Revisions" then "Edit Parent Revisions".
+* This will open a dialog where you will enter the patch number of the parent patch
+  (or patches). The patch number is of the form D<number> and you can find it by
+  looking at the URL for the review e.g. reviews.llvm/org/D12345.
+* Click "Save Parent Revisions" after entering them.
+* You should now see a "Stack" tab in the "Revision Contents" section of the web
+  interface, showing the parent patch that you added.
+
+Repeat this with each previous review until you reach the first in the series. This
+one won't have a parent since it's the start of the series.
+
+If you prefer to start with the first in the series and go forward, you can use the
+"Edit Child Revisions" option instead.
+
+.. _using-patch-summaries:
+
+Using patch summaries
+^^^^^^^^^^^^^^^^^^^^^
+
+This applies to new and existing reviews, uploaded with `arc` or the web interface.
+
+* Upload the first review and note its patch number, either with the web interface
+  or `arc`.
+* For each commit after that, add the following line to the commit message or patch
+  summary: "Depends on D<num>", where "<num>" is the patch number of the previous review.
+  This must be entirely on its own line, with a blank line before it.
+  For example::
+
+    [llvm] Example commit
+
+    Depends on D12345
+
+* If you want a single review to have multiple parent reviews then
+  add more with "and", for example: "Depends on D12344 and D12345".
+* Upload the commit with the web interface or `arc`
+  (``arc diff --verbatim`` to update an existing review).
+* You will see a "Stack" tab in the "Revision Contents" section of the review
+  in the web interface, showing the parent review.
+* Repeat these steps until you've uploaded or updated all the patches in
+  your series.
+
+When you push the patches, please remove the "Depends on" lines from the
+commit messages, since they add noise and duplicate git's implicit ordering.
+
+One frequently used workflow for creating a series of patches using patch summaries
+is based on git's rebasing. These steps assume that you have a series of commits that
+you have not posted for review, but can be adapted to update existing reviews.
+
+* git interactive rebase back to the first commit you want to upload for review::
+
+    git rebase -i HEAD~<number of commits you have written>
+
+* Mark all commits for editing by changing "pick" to "edit" in the instructions
+  git shows.
+* Start the rebase (usually by writing and closing the instructions).
+* For the first commit:
+
+  - Upload the current commit for a review (with ``arc diff`` or the web
+    interface).
+
+  - Continue to the next commit with ``git rebase --continue``
+
+* For the rest:
+
+  - Add the "Depends on..." line using ``git commit --amend``
+
+  - Upload for review.
+
+  - Continue the rebase.
+
+* Once the rebase is complete, you've created your patch series.
 
 .. _finding-potential-reviewers:
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D115519.394860.patch
Type: text/x-patch
Size: 3869 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20211216/cb0d66ee/attachment.bin>