Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: Add tip how to use GitHub code search to estimate the impact of a deprecation #29620

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 14, 2025
Merged

DOC: Add tip how to use GitHub code search to estimate the impact of a deprecation #29620

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ci/codespell-ignore-words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ oint
oly
te
thisy
ure
whis
wit
Copin
Expand Down
26 changes: 26 additions & 0 deletions doc/devel/api_changes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/search?q=%2F%5Cbfig%28ure%29%3F%5C.draw%5C%28%2F+language%3APython+NOT+is%3Afork&type=code>`_


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:
Expand Down
Loading