Add troubleshooting tips on pre-commit

Author: michaelosthege

docs/source/contributing/python_style.md

@@ -47,3 +47,31 @@ or, if you just want to manually run them on a subset of files,
 ```bash
 pre-commit run --files <file_1> <file_2> ... <file_n>
 ```
+
+## Gotchas & Troubleshooting
+__Pre-commit runs on staged files__
+
+If you have some `git` changes staged and other unstaged, the `pre-commit` will only run on the staged files.
+
+__Pre-commit repeatedly complains about the same formatting changes__
+
+Check the unstaged changes (see previous point).
+
+__Whitespace changes in the `environment-dev-*.yml` files__
+
+On Windows, there are some bugs in pre-commit hooks that can lead to changes in some environment YAML files.
+Until this is fixed upstream, you should __ignore these changes__.
+To actually make the commit, deactivate the automated `pre-commit` with `pre-commit uninstall` and make sure to run it manually with `pre-commit run --all`.
+
+__Failures in the `mypy` step__
+
+We are running static type checks with `mypy` to continuously improve the reliability and type safety of the PyMC codebase.
+However, there are many files with unresolved type problems, which is why we are allowing some files to fail the `mypy` check.
+
+If you are seeing the `mypy` step complain, chances are that you are in one of the following two situations:
+* 😕 Your changes introduced type problems in a file that was previously free of type problems.
+* 🥳 Your changes fixed type problems.
+
+In any case __read the logging output of the `mypy` hook__, because it contains the instructions how to proceed.
+
+You can also run the `mypy` check manually with `python scripts/run_mypy.py [--verbose]`.

docs/source/contributing/review_pr_pymc_examples.md

@@ -14,7 +14,7 @@ The most important guideline is the following: **When you aren't _completely_
 sure about something communicate it, ask around and (re)read the documentation**.
 :::
 
-pymc-examples is a huge collection of notebooks, covering many fields
+[pymc-examples](https://github.com/pymc-devs/pymc-examples/) is a huge collection of notebooks, covering many fields
 and applications of PyMC and Bayesian statistics. In addition,
 its HTML generation infrastructure has been improved by specialized
 people who were also paid so they could dedicate themselves to this task.