|
150
|
1 .. _phabricator-reviews:
|
|
|
2
|
|
|
3 =============================
|
|
|
4 Code Reviews with Phabricator
|
|
|
5 =============================
|
|
|
6
|
|
|
7 .. contents::
|
|
|
8 :local:
|
|
|
9
|
|
|
10 If you prefer to use a web user interface for code reviews, you can now submit
|
|
|
11 your patches for Clang and LLVM at `LLVM's Phabricator`_ instance.
|
|
|
12
|
|
|
13 While Phabricator is a useful tool for some, the relevant -commits mailing list
|
|
|
14 is the system of record for all LLVM code review. The mailing list should be
|
|
|
15 added as a subscriber on all reviews, and Phabricator users should be prepared
|
|
|
16 to respond to free-form comments in mail sent to the commits list.
|
|
|
17
|
|
|
18 Sign up
|
|
|
19 -------
|
|
|
20
|
|
|
21 To get started with Phabricator, navigate to `https://reviews.llvm.org`_ and
|
|
|
22 click the power icon in the top right. You can register with a GitHub account,
|
|
|
23 a Google account, or you can create your own profile.
|
|
|
24
|
|
|
25 Make *sure* that the email address registered with Phabricator is subscribed
|
|
|
26 to the relevant -commits mailing list. If you are not subscribed to the commit
|
|
|
27 list, all mail sent by Phabricator on your behalf will be held for moderation.
|
|
|
28
|
|
|
29 Note that if you use your git user name as Phabricator user name,
|
|
|
30 Phabricator will automatically connect your submits to your Phabricator user in
|
|
|
31 the `Code Repository Browser`_.
|
|
|
32
|
|
|
33 Requesting a review via the command line
|
|
|
34 ----------------------------------------
|
|
|
35
|
|
|
36 Phabricator has a tool called *Arcanist* to upload patches from
|
|
|
37 the command line. To get you set up, follow the
|
|
|
38 `Arcanist Quick Start`_ instructions.
|
|
|
39
|
|
|
40 You can learn more about how to use arc to interact with
|
|
|
41 Phabricator in the `Arcanist User Guide`_.
|
|
|
42
|
|
|
43 .. _phabricator-request-review-web:
|
|
|
44
|
|
|
45 Requesting a review via the web interface
|
|
|
46 -----------------------------------------
|
|
|
47
|
|
|
48 The tool to create and review patches in Phabricator is called
|
|
|
49 *Differential*.
|
|
|
50
|
|
|
51 Note that you can upload patches created through git.
|
|
|
52 To make reviews easier, please always include **as much context as
|
|
|
53 possible** with your diff! Don't worry, Phabricator
|
|
|
54 will automatically send a diff with a smaller context in the review
|
|
|
55 email, but having the full file in the web interface will help the
|
|
|
56 reviewer understand your code.
|
|
|
57
|
|
|
58 To get a full diff, use one of the following commands (or just use Arcanist
|
|
|
59 to upload your patch):
|
|
|
60
|
|
|
61 * ``git show HEAD -U999999 > mypatch.patch``
|
|
|
62 * ``git format-patch -U999999 @{u}``
|
|
|
63
|
|
|
64 Before uploading your patch, please make sure it is formatted properly, as
|
|
|
65 described in :ref:`How to Submit a Patch <format patches>`.
|
|
|
66
|
|
|
67 To upload a new patch:
|
|
|
68
|
|
|
69 * Click *Differential*.
|
|
|
70 * Click *+ Create Diff*.
|
|
|
71 * Paste the text diff or browse to the patch file. Click *Create Diff*.
|
|
|
72 * Leave this first Repository field blank. (We'll fill in the Repository
|
|
|
73 later, when sending the review.)
|
|
|
74 * Leave the drop down on *Create a new Revision...* and click *Continue*.
|
|
|
75 * Enter a descriptive title and summary. The title and summary are usually
|
|
|
76 in the form of a :ref:`commit message <commit messages>`.
|
|
|
77 * Add reviewers (see below for advice). (If you set the Repository field
|
|
|
78 correctly, llvm-commits or cfe-commits will be subscribed automatically;
|
|
|
79 otherwise, you will have to manually subscribe them.)
|
|
|
80 * In the Repository field, enter the name of the project (LLVM, Clang,
|
|
|
81 etc.) to which the review should be sent.
|
|
|
82 * Click *Save*.
|
|
|
83
|
|
|
84 To submit an updated patch:
|
|
|
85
|
|
|
86 * Click *Differential*.
|
|
|
87 * Click *+ Create Diff*.
|
|
|
88 * Paste the updated diff or browse to the updated patch file. Click *Create Diff*.
|
|
|
89 * Select the review you want to from the *Attach To* dropdown and click
|
|
|
90 *Continue*.
|
|
|
91 * Leave the Repository field blank. (We previously filled out the Repository
|
|
|
92 for the review request.)
|
|
|
93 * Add comments about the changes in the new diff. Click *Save*.
|
|
|
94
|
|
|
95 Choosing reviewers: You typically pick one or two people as initial reviewers.
|
|
|
96 This choice is not crucial, because you are merely suggesting and not requiring
|
|
|
97 them to participate. Many people will see the email notification on cfe-commits
|
|
|
98 or llvm-commits, and if the subject line suggests the patch is something they
|
|
|
99 should look at, they will.
|
|
|
100
|
|
|
101
|
|
|
102 .. _finding-potential-reviewers:
|
|
|
103
|
|
|
104 Finding potential reviewers
|
|
|
105 ---------------------------
|
|
|
106
|
|
|
107 Here are a couple of ways to pick the initial reviewer(s):
|
|
|
108
|
|
|
109 * Use ``git blame`` and the commit log to find names of people who have
|
|
|
110 recently modified the same area of code that you are modifying.
|
|
|
111 * Look in CODE_OWNERS.TXT to see who might be responsible for that area.
|
|
|
112 * If you've discussed the change on a dev list, the people who participated
|
|
|
113 might be appropriate reviewers.
|
|
|
114
|
|
|
115 Even if you think the code owner is the busiest person in the world, it's still
|
|
|
116 okay to put them as a reviewer. Being the code owner means they have accepted
|
|
|
117 responsibility for making sure the review happens.
|
|
|
118
|
|
|
119 Reviewing code with Phabricator
|
|
|
120 -------------------------------
|
|
|
121
|
|
|
122 Phabricator allows you to add inline comments as well as overall comments
|
|
|
123 to a revision. To add an inline comment, select the lines of code you want
|
|
|
124 to comment on by clicking and dragging the line numbers in the diff pane.
|
|
|
125 When you have added all your comments, scroll to the bottom of the page and
|
|
|
126 click the Submit button.
|
|
|
127
|
|
|
128 You can add overall comments in the text box at the bottom of the page.
|
|
|
129 When you're done, click the Submit button.
|
|
|
130
|
|
|
131 Phabricator has many useful features, for example allowing you to select
|
|
|
132 diffs between different versions of the patch as it was reviewed in the
|
|
|
133 *Revision Update History*. Most features are self descriptive - explore, and
|
|
|
134 if you have a question, drop by on #llvm in IRC to get help.
|
|
|
135
|
|
|
136 Note that as e-mail is the system of reference for code reviews, and some
|
|
|
137 people prefer it over a web interface, we do not generate automated mail
|
|
|
138 when a review changes state, for example by clicking "Accept Revision" in
|
|
|
139 the web interface. Thus, please type LGTM into the comment box to accept
|
|
|
140 a change from Phabricator.
|
|
|
141
|
|
|
142 Committing a change
|
|
|
143 -------------------
|
|
|
144
|
|
|
145 Once a patch has been reviewed and approved on Phabricator it can then be
|
|
|
146 committed to trunk. If you do not have commit access, someone has to
|
|
|
147 commit the change for you (with attribution). It is sufficient to add
|
|
|
148 a comment to the approved review indicating you cannot commit the patch
|
|
|
149 yourself. If you have commit access, there are multiple workflows to commit the
|
|
|
150 change. Whichever method you follow it is recommended that your commit message
|
|
|
151 ends with the line:
|
|
|
152
|
|
|
153 ::
|
|
|
154
|
|
|
155 Differential Revision: <URL>
|
|
|
156
|
|
|
157 where ``<URL>`` is the URL for the code review, starting with
|
|
|
158 ``https://reviews.llvm.org/``.
|
|
|
159
|
|
|
160 This allows people reading the version history to see the review for
|
|
|
161 context. This also allows Phabricator to detect the commit, close the
|
|
|
162 review, and add a link from the review to the commit.
|
|
|
163
|
|
|
164 Note that if you use the Arcanist tool the ``Differential Revision`` line will
|
|
|
165 be added automatically. If you don't want to use Arcanist, you can add the
|
|
|
166 ``Differential Revision`` line (as the last line) to the commit message
|
|
|
167 yourself.
|
|
|
168
|
|
|
169 Using the Arcanist tool can simplify the process of committing reviewed code as
|
|
|
170 it will retrieve reviewers, the ``Differential Revision``, etc from the review
|
|
|
171 and place it in the commit message. You may also commit an accepted change
|
|
|
172 directly using ``git llvm push``, per the section in the :ref:`getting started
|
|
|
173 guide <commit_from_git>`.
|
|
|
174
|
|
|
175 Note that if you commit the change without using Arcanist and forget to add the
|
|
|
176 ``Differential Revision`` line to your commit message then it is recommended
|
|
|
177 that you close the review manually. In the web UI, under "Leap Into Action" put
|
|
|
178 the git revision number in the Comment, set the Action to "Close Revision" and
|
|
|
179 click Submit. Note the review must have been Accepted first.
|
|
|
180
|
|
|
181
|
|
|
182 Committing someone's change from Phabricator
|
|
|
183 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
184
|
|
|
185 On a clean Git repository on an up to date ``master`` branch run the
|
|
|
186 following (where ``<Revision>`` is the Phabricator review number):
|
|
|
187
|
|
|
188 ::
|
|
|
189
|
|
|
190 arc patch D<Revision>
|
|
|
191
|
|
|
192
|
|
|
193 This will create a new branch called ``arcpatch-D<Revision>`` based on the
|
|
|
194 current ``master`` and will create a commit corresponding to ``D<Revision>`` with a
|
|
|
195 commit message derived from information in the Phabricator review.
|
|
|
196
|
|
|
197 Check you are happy with the commit message and amend it if necessary. Then,
|
|
|
198 make sure the commit is up-to-date, and commit it. This can be done by running
|
|
|
199 the following:
|
|
|
200
|
|
|
201 ::
|
|
|
202
|
|
|
203 git pull --rebase origin master
|
|
|
204 git show # Ensure the patch looks correct.
|
|
|
205 ninja check-$whatever # Rerun the appropriate tests if needed.
|
|
|
206 git llvm push
|
|
|
207
|
|
|
208 Or
|
|
|
209
|
|
|
210 ::
|
|
|
211
|
|
|
212 arc land D<Revision>
|
|
|
213
|
|
|
214
|
|
|
215 Abandoning a change
|
|
|
216 -------------------
|
|
|
217
|
|
|
218 If you decide you should not commit the patch, you should explicitly abandon
|
|
|
219 the review so that reviewers don't think it is still open. In the web UI,
|
|
|
220 scroll to the bottom of the page where normally you would enter an overall
|
|
|
221 comment. In the drop-down Action list, which defaults to "Comment," you should
|
|
|
222 select "Abandon Revision" and then enter a comment explaining why. Click the
|
|
|
223 Submit button to finish closing the review.
|
|
|
224
|
|
|
225 Status
|
|
|
226 ------
|
|
|
227
|
|
|
228 Please let us know whether you like it and what could be improved! We're still
|
|
|
229 working on setting up a bug tracker, but you can email klimek-at-google-dot-com
|
|
|
230 and chandlerc-at-gmail-dot-com and CC the llvm-dev mailing list with questions
|
|
|
231 until then. We also could use help implementing improvements. This sadly is
|
|
|
232 really painful and hard because the Phabricator codebase is in PHP and not as
|
|
|
233 testable as you might like. However, we've put exactly what we're deploying up
|
|
|
234 on an `llvm-reviews GitHub project`_ where folks can hack on it and post pull
|
|
|
235 requests. We're looking into what the right long-term hosting for this is, but
|
|
|
236 note that it is a derivative of an existing open source project, and so not
|
|
|
237 trivially a good fit for an official LLVM project.
|
|
|
238
|
|
|
239 .. _LLVM's Phabricator: https://reviews.llvm.org
|
|
|
240 .. _`https://reviews.llvm.org`: https://reviews.llvm.org
|
|
|
241 .. _Code Repository Browser: https://reviews.llvm.org/diffusion/
|
|
|
242 .. _Arcanist Quick Start: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/
|
|
|
243 .. _Arcanist User Guide: https://secure.phabricator.com/book/phabricator/article/arcanist/
|
|
|
244 .. _llvm-reviews GitHub project: https://github.com/r4nt/llvm-reviews/
|
