diff --git a/ci/codespell-ignore-words.txt b/ci/codespell-ignore-words.txt index 5cd80beaa23c..e28e7ef99fd7 100644 --- a/ci/codespell-ignore-words.txt +++ b/ci/codespell-ignore-words.txt @@ -14,6 +14,7 @@ oint oly te thisy +ure whis wit Copin diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst index 24b088836561..deba4deaf521 100644 --- a/doc/devel/api_changes.rst +++ b/doc/devel/api_changes.rst @@ -54,6 +54,32 @@ them. While the decision is case-by-case, evaluation criteria include: Deprecate API ------------- +When deciding to deprecate API we carefully consider the balance between the advantages +(clearer interfaces, better usability, less maintenance) and the disadvantages (users +have to learn new API and have to modify existing code). + +.. tip:: + + A rough estimate on the current usage of an API can be obtained by a GitHub code + search. A good search pattern is typically + ``[expression] language:Python NOT is:fork``. ``[expression]`` may be a simple + string, but often regular expressions are helpful to exclude incorrect matches. + You can start simple and look at the search results, if there are too many + incorrect matches, gradually refine your search criteria. + + *Example*: Calls of the method ``Figure.draw()`` could be matched using + ``/\bfig(ure)?\.draw\(/``. This expression employs a number of patterns: + + - Add the opening bracket ``(`` after the method name to only find method calls. + - Include a common object name if there are otherwise too many false positives. + There are many ``draw()`` functions out there, but the ones we are looking for + are likely called via ``fig.draw()`` or ``figure.draw()``. + - Use the word boundary marker ``\b`` to make sure your expression is not a + matching as part of a longer word. + + `Link to the resulting GitHub search `_ + + API changes in Matplotlib have to be performed following the deprecation process below, except in very rare circumstances as deemed necessary by the development team. Generally API deprecation happens in two stages: