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

Rephrase so that method 1 is using the add revisions in the web interface and
method 2 is using "Depends on" with either arc or the web interface.

Add note that you can have multiple parent reviews. I tested that "and"
works to add more.

Implement phrasing comments.

Double backtick where showing a command so that dash dash isn't merged
visually into one character. Put the rebase command in its own box
since it didn't make sense on the end of a line.

Removed the "Differential review" line from the example commit since
that's only there once you upload it with arc.


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,87 @@
 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
+  (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.)
+
+The second method may be less work. This works for 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 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
+
+    Depends on D12345
+
+* If you want a single commit to have multiple parent commits then
+  add more with "and". "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.
+
+As before, repeat this until you've uploaded or updated all the patches in
+your series.
+
+When you finally push the series to Github, 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 this uses git's rebasing. These steps assume
+that you have a series of commits that you have not posted for review and use
+`arc` to upload them. They can be adapted if you're using the web interface,
+or updating 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:
+
+  - ``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.394578.patch
Type: text/x-patch
Size: 3720 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20211215/3307acd9/attachment.bin>