[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 393905.
DavidSpickett added a comment.

Link to Mozilla docs as well as describing both methods in our own docs.

Expand the git rebase workflow suggestion that is now "frequently used"
not "reccomended".


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,76 @@
 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)
+
+The first is using the web interface. It 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(es).
+  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.)
+
+The second method is less work for you but assumes you are using `arc`. This can be
+done when updating a review as well as uploading it for the first time.
+
+* Upload the first review with `arc`. Note its patch number.
+* For each commit after that add a line to the commit message. "Depends on D<num>"
+  where "<num>" is the patch number of the previous commit.
+  This must be entirely on its own line, with a blank line before it.
+  For example::
+
+    [llvm] Example commit for Phabricator docs
+
+    Differential revision: https://reviews.llvm.org/D12345
+
+    Depends on D12344
+* Upload the commit for review with `arc diff`.
+* You will see a "Stack" tab in the "Revision Contents" section of the review
+  in the web interface, showing the parent review.
+
+As before, repeat this until you've uploaded or updated all the patches in
+your series.
+
+One frequently used workflow for this uses git's rebasing. These steps assume
+that you have a series of commits that you have not posted for review.
+
+* git interactive rebase back to the first commit you want to upload for review.
+  `git rebase -i HEAD~<number of commits you've 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:
+
+  - `arc diff` to upload for review.
+
+  - 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.393905.patch
Type: text/x-patch
Size: 3307 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20211213/573d0dc5/attachment.bin>