diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst index 9311f39b6e697..5ee07fcec5bf9 100644 --- a/llvm/docs/Contributing.rst +++ b/llvm/docs/Contributing.rst @@ -73,15 +73,33 @@ recent commit: % git clang-format HEAD~1 -Note that this modifies the files, but doesn't commit them -- you'll likely want -to run +.. note:: + For some patches, formatting them may add changes that obscure the intent of + the patch. For example, adding to an enum that was not previously formatted + may result in the entire enum being reformatted. This happens because not all + of the LLVM Project conforms to LLVM's clang-format style at this time. + + If you think that this might be the case for your changes, or are unsure, we + recommend that you add the formatting changes as a **separate commit** within + the Pull Request. + + Reviewers may request that this formatting commit be made into a separate Pull + Request that will be merged before your actual changes. + + This means that if the formatting changes are the first commit, you will have + an easier time doing this. If they are not, that is ok too, but you will have + to do a bit more work to separate it out. + +Note that ``git clang-format`` modifies the files, but does not commit them -- +you will likely want to run one of the following to add the changes to a commit: .. code-block:: console + # To create a new commit. + % git commit -a + # To add to the most recent commit. % 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