Add discussion of git-format-patch to Phabricator.html

[kbarton]

Summary

There is a discussion of git-format-patch in GettingStarted guide, but no mention of it in the Phabricator.html page.

[delcypher]

Thanks for the patch. I didn't know that this information was missing from our docs!

llvm/docs/Phabricator.rst

65

I think this needs to be put into its own section because it's not specific to "Requesting a review via the web interface". Formatting is really about preparing for a review rather than requesting it.

Perhaps this information belongs in "How to Submit a Patch" section of the contributing guide and then we could reference that section from this document?

Thoughts?

[kbarton]

• Move description of clang-format to Contributing.rst and add a link to Phabricator.rst to reference it.

[kbarton]

Thanks for the review @delcypher!

I agree it's probably better to move this. I've put it under the "How to Submit a Patch" section in Contributing.rst, and added a link to it in Phabricator.rst as you suggested.

The only thing I'm not sure about is whether to create a new subsection for it, or just leave it as inline text and link to the paragraph directly (which is what I did). The problem I had with a new subsection was getting "out" of the new subsection for the rest of the instructions under "How to Submit a Patch" (hopefully that makes sense).

[delcypher]

The only thing I'm not sure about is whether to create a new subsection for it, or just leave it as inline text and link to the paragraph directly (which is what I did).

I think as the patch is now is fine.

The problem I had with a new subsection was getting "out" of the new subsection for the rest of the instructions under "How to Submit a Patch" (hopefully that makes sense).

I'm not sure what you mean here.

[kbarton]

The problem I had with a new subsection was getting "out" of the new subsection for the rest of the instructions under "How to Submit a Patch" (hopefully that makes sense).

I'm not sure what you mean here.

I wouldn't worry about it - this is more my random meanderings.... If you're OK with this, I'll commit it as is.

Thanks again for the review!

llvm/docs/Contributing.rst

 Bigger Pieces of Work
 ---------------------
 In case you are interested in taking on a bigger piece of work, a list of
 interesting projects is maintained at the `LLVM's Open Projects page`_. In case
 you are interested in working on any of these projects, please send a mail to
 the `LLVM Developer's mailing list`_, so that we know the project is being
 worked on.
 
-
 How to Submit a Patch
 =====================
 Once you have a patch ready, it is time to submit it. The patch should:
 
 * include a small unit test
 * conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly.
 * not contain any unrelated changes
 * be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
 
+.. _format patches:
+
+Before sending a patch for review, please also try to ensure it is
+formatted properly. We use ``clang-format`` for this, which has git integration
+through the ``git-clang-format`` script. On some systems, it may already be
+installed (or be installable via your package manager). If so, you can simply
+run it -- the following command will format only the code changed in the most
+recent commit:
+
+.. code-block:: console
+
+  % git clang-format HEAD~1
+
+Note that this modifies the files, but doesn't commit them -- you'll likely want
+to run
+
+.. code-block:: console
+
+  % git commit --amend -a
+
+in order to update the last commit with all pending changes.
+
+.. note::
+  If you don't already have ``clang-format`` or ``git clang-format`` installed
+  on your system, the ``clang-format`` binary will be built alongside clang, and
+  the git integration can be run from
+  ``clang/tools/clang-format/git-clang-format``.
+
+
 To get a patch accepted, it has to be reviewed by the LLVM community. This can
 be done using `LLVM's Phabricator`_ or the llvm-commits mailing list.
 Please  follow :ref:`Phabricator#requesting-a-review-via-the-web-interface <phabricator-request-review-web>`
 to request a review using Phabricator.
 
 To make sure the right people see your patch, please select suitable reviewers
 and add them to your patch when requesting a review. Suitable reviewers are the
 code owner (see CODE_OWNERS.txt) and other people doing work in the area your

llvm/docs/Phabricator.rst

 
 To get a full diff, use one of the following commands (or just use Arcanist
 to upload your patch):
 
 * ``git show HEAD -U999999 > mypatch.patch``
 * ``git format-patch -U999999 @{u}``
 * ``svn diff --diff-cmd=diff -x -U999999``
 
+Before uploading your patch, please make sure it is formatted properly, as
+described in :ref:`How to Submit a Patch <format patches>`.
+
 To upload a new patch:
 
 * Click *Differential*.
 * Click *+ Create Diff*.
 * Paste the text diff or browse to the patch file. Click *Create Diff*.
 * Leave this first Repository field blank. (We'll fill in the Repository
   later, when sending the review.)
 * Leave the drop down on *Create a new Revision...* and click *Continue*.