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