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