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,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 `_ +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 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" + where "" 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~ + +* 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: