diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst index 9d87142b0984f..ed7faa8b56f2d 100644 --- a/llvm/docs/CodingStandards.rst +++ b/llvm/docs/CodingStandards.rst @@ -113,13 +113,43 @@ section. Python code in the LLVM repository should only use language features available in this version of Python. The Python code within the LLVM repository should adhere to the formatting guidelines -outlined in `PEP-8 `_. +outlined in `PEP 8 `_. -For consistency and to limit churn, code should be automatically formatted with the -`black `_ utility. Black allows changing the formatting -rules based on major version. In order to avoid unnecessary churn in the formatting rules +For consistency and to limit churn, code should be automatically formatted with +the `black `_ utility, which is PEP 8 compliant. +Use its default rules. For example, avoid specifying ``--line-length`` even +though it does not default to 80. The default rules can change between major +versions of black. In order to avoid unnecessary churn in the formatting rules, we currently use black version 23.x in LLVM. +When contributing a patch unrelated to formatting, you should format only the +Python code that the patch modifies. For this purpose, use the `darker +`_ utility, which runs default black rules +over only the modified Python code. Doing so should ensure the patch will pass +the Python format checks in LLVM's pre-commit CI, which also uses darker. When +contributing a patch specifically for reformatting Python files, use black, +which currently only supports formatting entire files. + +Here are some quick examples, but see the black and darker documentation for +details: + +.. code-block:: bash + + $ pip install black=='23.*' darker # install black 23.x and darker + $ darker test.py # format uncommitted changes + $ darker -r HEAD^ test.py # also format changes from last commit + $ black test.py # format entire file + +Instead of individual file names, you can specify directories to +darker, and it will find the changed files. However, if a directory is +large, like a clone of the LLVM repository, darker can be painfully +slow. In that case, you might wish to use git to list changed files. +For example: + +.. code-block:: bash + + $ darker -r HEAD^ $(git diff --name-only HEAD^) + Mechanical Source Issues ========================