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

- Add section titles and used that to better signal what the rebasing suggestion refers to.
- Incorporated grammar changes.
- Removed full stops from end of lines that ended in a command. Since a monospace "." looks the same as the default style "." and could be seen as being part of the command.
- Changed a few instances of using "commit message" where I mean the patch summary. (which means it makes more sense if you're in the web UI)


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 the steps described above is based on git's
+rebasing. These steps assume that you have a series of commits that you have
+not posted for review and use will 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.394823.patch
Type: text/x-patch
Size: 3869 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20211216/a3ebe7a5/attachment.bin>