diff --git a/llvm/docs/Phabricator.rst b/llvm/docs/Phabricator.rst --- a/llvm/docs/Phabricator.rst +++ b/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 `_ +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 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", where "" 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~ + +* 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: