[doc pre-commit integration] Details about known caveats of using multiple processes

Refs microsoft/vscode-pylint#454
Also add known caveats for custom parallization.

Closes #9341

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>

Author: Pierre-Sassoulas

.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/faq.rst

@@ -67,6 +67,28 @@ to not be included as default messages.
 You can see the plugin you need to explicitly :ref:`load in the technical reference
 <user_guide/checkers/extensions:optional checkers>`.
 
+I want to use pylint on each keystroke in my IDE, how can I do that ?
+---------------------------------------------------------------------
+
+Don't do it: pylint's full suite of checks is not fast enough for that and never
+will be. pylint is best suited for linting on save for small projects, or for a continuous
+integration job or a git ``pre-push`` hook for big projects. The larger your repository
+is, the slower pylint will be.
+
+If you want to make pylint faster for this type of use case, you can use the ``--errors-only``
+option, which will remove all the refactor, convention, and warning checks. You can also disable
+checks with inherently high complexity that need to analyse the full code base like
+``duplicate-code`` or ``cyclic-import`` (this list is not exhaustive).
+
+Why do I have non-deterministic results when I try to parallelize pylint ?
+--------------------------------------------------------------------------
+
+pylint should analyse all your code at once in order to best infer the
+actual values that result from calls. If only some of the files are given, pylint might
+miss a particular value's type and produce inferior inference for the subset. Parallelization
+of pylint is not easy; we also discourage the use of the ``-j`` option if this matters to you.
+
+
 Which messages should I disable to avoid duplicates if I use other popular linters ?
 ------------------------------------------------------------------------------------
 

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

@@ -3,10 +3,28 @@
 Pre-commit integration
 ======================
 
-``pylint`` can be used as a `pre-commit <https://pre-commit.com>`_ hook.
+``pylint`` can be used as a `pre-commit <https://pre-commit.com>`_ hook. We however
+discourage it as pylint -- due to its speed -- is more suited to a continuous integration
+job or a git ``pre-push`` hook, especially if your repository is large.
 
 Since ``pylint`` needs to import modules and dependencies to work correctly, the
-hook only works with a local installation of ``pylint`` (in your environment).
+hook only works with a local installation of ``pylint`` (in your environment). It means
+it can't be used with ``pre-commit.ci``, and you will need to add the following to your
+``.pre-commit-config.yaml`` ::
+
+.. sourcecode:: yaml
+
+    ci:
+      skip: [pylint]
+
+Another limitation is that pylint should analyse all your code at once in order to best infer the
+actual values that result from 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 slices
+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 should be set to ``true`` if correctness and determinism
+are more important than parallelization to you.
+
 If you installed ``pylint`` locally it can be added to ``.pre-commit-config.yaml``
 as follows:
 
@@ -19,6 +37,7 @@ as follows:
         entry: pylint
         language: system
         types: [python]
+        require_serial: true
         args:
           [
             "-rn", # Only display messages

doc/user_guide/usage/run.rst

@@ -153,6 +153,7 @@ Parallel execution
 It is possible to speed up the execution of Pylint. If the running computer
 has more CPUs than one, then the work for checking all files could be spread across all
 cores via Pylints's sub-processes.
+
 This functionality is exposed via the ``-j`` command-line parameter.
 If the provided number is 0, then the total number of CPUs will be autodetected and used.
 
@@ -164,6 +165,15 @@ This will spawn 4 parallel Pylint sub-process, where each provided module will
 be checked in parallel. Discovered problems by checkers are not displayed
 immediately. They are shown just after checking a module is complete.
 
+You can also do your own parallelization by launching pylint multiple times on subsets
+of your files (like ``pre-commit`` with the default ``require_serial=false`` does).
+Be aware, though: pylint should analyse all your code at once in order to best infer
+the actual values that result from calls. If only some of the files are given, pylint
+might miss a particular value's type and produce inferior inference for the subset.
+It can also be unexpectedly different when the file set changes because the new
+slicing can change the inference. So, don't do this if correctness and determinism
+are important to you.
+
 Exit codes
 ----------