@@ -54,6 +54,31 @@ them. While the decision is case-by-case, evaluation criteria include:
5454Deprecate API
5555-------------
5656
57+ API stability and not breaking user code is a high value. When deciding to deprecate
58+ API we carefully consider the balance between the advantages (clearer interfaces,
59+ better usability, less maintenance) and the disadvantages (users have to learn new API
60+ and have to modify existing code).
61+
62+ .. tip ::
63+
64+ A rough estimate on the current usage of an API can be obtained by a GitHub code
65+ search. A good search pattern is typically
66+ ``[expression] language:Python NOT is:fork ``. ``[expression] `` may be a simple
67+ string, but often regular expressions are helpful to exclude incorrect matches.
68+
69+ *Example *: Calls of the method ``Figure.draw() `` could be matched using
70+ ``/\bfig(ure)?\.draw\(/ ``. This expression employs a number of patterns:
71+
72+ - Add the opening bracket ``( `` after the method name to only find method calls.
73+ - Include a common object name if there are otherwise too many false positives.
74+ There are many ``draw() `` functions out there, but the ones we are looking for
75+ are likely called via ``fig.draw() `` or ``figure.draw() ``.
76+ - Use the word boundary marker ``\b `` to make sure your expression is not a
77+ matching as part of a longer word.
78+
79+ `Link to the resulting GitHub search <https://github.com/search?q=%2F%5Cbfig%28ure%29%3F%5C.draw%5C%28%2F+language%3APython+NOT+is%3Afork&type=code >`_
80+
81+
5782API changes in Matplotlib have to be performed following the deprecation process
5883below, except in very rare circumstances as deemed necessary by the development
5984team. Generally API deprecation happens in two stages:
0 commit comments