Skip to content

Commit f845497

Browse files
[llvm][Docs] Explain how to handle excessive formatting changes (#126239)
Based on some feedback in Discord about a PR where a reviewer asked the author to move the formatting changes to a new PR, which appears to contradict the current form of this document. I've added an explanation here, before the point where the author would be committing any of the formatting changes. There are other ways this can go, for example some projects don't want the churn of formatting, or you can pre-emptively send a formatting PR, but I don't think enumerating them all here will help the audience for this text. So I've recomended one path that will start them off well, and can branch off if the reviewers make requests.
1 parent cab893a commit f845497

File tree

1 file changed

+22
-4
lines changed

1 file changed

+22
-4
lines changed

llvm/docs/Contributing.rst

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,15 +73,33 @@ recent commit:
7373
7474
% git clang-format HEAD~1
7575
76-
Note that this modifies the files, but doesn't commit them -- you'll likely want
77-
to run
76+
.. note::
77+
For some patches, formatting them may add changes that obscure the intent of
78+
the patch. For example, adding to an enum that was not previously formatted
79+
may result in the entire enum being reformatted. This happens because not all
80+
of the LLVM Project conforms to LLVM's clang-format style at this time.
81+
82+
If you think that this might be the case for your changes, or are unsure, we
83+
recommend that you add the formatting changes as a **separate commit** within
84+
the Pull Request.
85+
86+
Reviewers may request that this formatting commit be made into a separate Pull
87+
Request that will be merged before your actual changes.
88+
89+
This means that if the formatting changes are the first commit, you will have
90+
an easier time doing this. If they are not, that is ok too, but you will have
91+
to do a bit more work to separate it out.
92+
93+
Note that ``git clang-format`` modifies the files, but does not commit them --
94+
you will likely want to run one of the following to add the changes to a commit:
7895

7996
.. code-block:: console
8097
98+
# To create a new commit.
99+
% git commit -a
100+
# To add to the most recent commit.
81101
% git commit --amend -a
82102
83-
in order to update the last commit with all pending changes.
84-
85103
.. note::
86104
If you don't already have ``clang-format`` or ``git clang-format`` installed
87105
on your system, the ``clang-format`` binary will be built alongside clang, and

0 commit comments

Comments
 (0)