1 files changed, 80 insertions, 0 deletions
diff --git a/doc/develop/python_cq.rst b/doc/develop/python_cq.rst
new file mode 100644
index 0000000000..3f99f1d9c0
--- /dev/null
+++ b/doc/develop/python_cq.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Python code quality
+===================
+
+U-Boot has about 60k lines of Python code, mainly in the following areas:
+
+- tests
+- pytest hooks
+- patman patch submission tool
+- buildman build / analysis tool
+- dtoc devicetree-to-C tool
+- binman firmware packaging tool
+
+`PEP 8`_ is used for the code style, with the single quote (') used by default for
+strings and double quote for doc strings. All non-trivial functions should be
+commented.
+
+Pylint is used to help check this code and keep a consistent code style. The
+build system tracks the current 'score' of the source code and detects
+regressions in any module.
+
+To run this locally you should use this version of pylint::
+
+    # pylint --version
+    pylint 2.11.1
+    astroid 2.8.6
+    Python 3.8.10 (default, Sep 28 2021, 16:10:42)
+    [GCC 9.3.0]
+
+
+You should be able to select and this install other required tools with::
+
+    pip install pylint==2.11.1
+    pip install -r test/py/requirements.txt
+    pip install asteval pyopenssl
+
+Note that if your distribution is a year or two old, you make need to use `pip3`
+instead.
+
+To configure pylint, make sure it has docparams enabled, e.g. with::
+
+    echo "[MASTER]" >> .pylintrc
+    echo "load-plugins=pylint.extensions.docparams" >> .pylintrc
+
+Once everything is ready, use this to check the code::
+
+    make pylint
+
+This creates a directory called `pylint.out` which contains the pylint output
+for each Python file in U-Boot. It also creates a summary file called
+`pylint.cur` which shows the pylint score for each module::
+
+    _testing 0.83
+    atf_bl31 -6.00
+    atf_fip 0.49
+    binman.cbfs_util 7.70
+    binman.cbfs_util_test 9.19
+    binman.cmdline 7.73
+    binman.control 4.39
+    binman.elf 6.42
+    binman.elf_test 5.41
+    ...
+
+This file is in alphabetical order. The build system compares the score of each
+module to `scripts/pylint.base` (which must also be sorted and have exactly the
+same modules in it) and reports any files where the score has dropped. Use
+pylint to check what is wrong and fix up the code before you send out your
+patches.
+
+New or removed files results in an error which can be resolved by updating the
+`scripts/pylint.base` file to add/remove lines for those files, e.g.::
+
+    meld pylint.cur scripts/pylint.base
+
+If the pylint version is updated in CI, this may result in needing to regenerate
+`scripts/pylint.base`.
+
+
+.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/