[doc pre-commit integration] Details about known caveats of using mul…

…tiple processes

Closes #9341

.pre-commit-config.yaml

@@ -77,6 +77,9 @@ repos:
         entry: pylint
         language: system
         types: [python]
+        # Not that problematic to run in parallel see Pre-commit
+        # integration in the doc for details
+        # require_serial: true
         args: ["-rn", "-sn", "--rcfile=pylintrc", "--fail-on=I"]
         exclude: tests(/\w*)*/functional/|tests/input|tests(/\w*)*data/|doc/
       # We define an additional manual step to allow running pylint with a spelling

doc/user_guide/installation/pre-commit-integration.rst

@@ -7,6 +7,15 @@ Pre-commit integration
 
 Since ``pylint`` needs to import modules and dependencies to work correctly, the
 hook only works with a local installation of ``pylint`` (in your environment).
+
+Another limitation is that pylint should analyses all your code at once in order to best infer the
+actual values that are passed in calls. If only some of the files are given pylint might
+miss a particular value's type and produce inferior inference for the subset. Since pre-commit slice
+the files given to it in order to parallelize the processing the result can be degraded.
+It can also be unexpectedly different when the file set changes because the new slicing can change
+the inference. Thus the ``require_serial`` option could be set to ``true`` if correctness and determinism
+is more important than parallelization to you.
+
 If you installed ``pylint`` locally it can be added to ``.pre-commit-config.yaml``
 as follows:
 
@@ -19,6 +28,7 @@ as follows:
         entry: pylint
         language: system
         types: [python]
+        require_serial: true
         args:
           [
             "-rn", # Only display messages