Add note about thread safety to FAQ.

anntzer · anntzer · commit 51cfd6b67a24 · 2019-01-27T12:26:33.000+01:00
Looks like there are more and more people running into threading issues.
Add a generic FAQ entry for them, and edit the ISSUE_TEMPLATE to perhaps
decrease the number of such reports.
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -9,7 +9,10 @@
 
 **Code for reproduction**
 
-<!--A minimum code snippet required to reproduce the bug, also minimizing the number of dependencies required-->
+<!--A minimum code snippet required to reproduce the bug.
+Please make sure to minimize the number of dependencies required, and provide
+any necessary plotted data.
+Avoid using threads, as Matplotlib is (explicitly) not thread-safe.-->
 
 ```python
 # Paste your code here
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -540,6 +540,18 @@ Tukey's `box plots <http://matplotlib.org/examples/pylab_examples/boxplot_demo.h
 `Violin plots <http://matplotlib.org/examples/statistics/violinplot_demo.html>`_ are closely related to box plots but add useful information such as the distribution of the sample data (density trace).
 Violin plots were added in Matplotlib 1.4.
 
+.. _how-to-threads:
+
+Working with threads
+--------------------
+
+Matplotlib is not thread-safe: in fact, there are known race conditions
+that affect certain artists.  Hence, if you work with threads, it is your
+responsibility to set up the proper locks to serialize access to Matplotlib
+artists.
+
+Note that (for the case where you are working with an interactive backend) most
+GUI backends *require* being run from the main thread as well.
 
 .. _howto-contribute:
 
