Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 6522557

Browse filesBrowse files
story645story645
committed
reorganizing contributing docs to clean up toc, create seperation between guidelines, and make contributing guide more newbie oriented
1 parent 4524fdb commit 6522557
Copy full SHA for 6522557

File tree

7 files changed

+982
-918
lines changed
Filter options

7 files changed

+982
-918
lines changed

‎doc/devel/api_changes.rst

Copy file name to clipboard
+206Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
.. _api_changes:
2+
3+
API changes
4+
===========
5+
6+
API consistency and stability are of great value; Therefore, API changes
7+
(e.g. signature changes, behavior changes, removals) will only be conducted
8+
if the added benefit is worth the effort of adapting existing code.
9+
10+
Because we are a visualization library, our primary output is the final
11+
visualization the user sees; therefore, the appearance of the figure is part of
12+
the API and any changes, either semantic or :ref:`esthetic <color_changes>`,
13+
are backwards-incompatible API changes.
14+
15+
.. _api_whats_new:
16+
17+
Announce changes, deprecations, and new features
18+
------------------------------------------------
19+
20+
When adding or changing the API in a backward in-compatible way, please add the
21+
appropriate :ref:`versioning directive <versioning-directives>` and document it
22+
for the release notes and add the entry to the appropriate folder:
23+
24+
+-------------------+-----------------------------+----------------------------------------------+
25+
| addition | versioning directive | announcement folder |
26+
+===================+=============================+==============================================+
27+
| new feature | ``.. versionadded:: 3.N`` | :file:`doc/users/next_whats_new/` |
28+
+-------------------+-----------------------------+----------------------------------------------+
29+
| API change | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/[kind]` |
30+
+-------------------+-----------------------------+----------------------------------------------+
31+
32+
API deprecations are first introduced and then expired. During the introduction
33+
period, users are warned that the API *will* change in the future.
34+
During the expiration period, code is changed as described in the notice posted
35+
during the introductory period.
36+
37+
+-----------+--------------------------------------------------+----------------------------------------------+
38+
| stage | required changes | announcement folder |
39+
+===========+==================================================+==============================================+
40+
| introduce | :ref:`introduce deprecation <intro-deprecation>` | :file:`doc/api/next_api_changes/deprecation` |
41+
+-----------+--------------------------------------------------+----------------------------------------------+
42+
| expire | :ref:`expire deprecation <expire-deprecation>` | :file:`doc/api/next_api_changes/[kind]` |
43+
+-----------+--------------------------------------------------+----------------------------------------------+
44+
45+
For both change notes and what's new, please avoid using references in section
46+
titles, as it causes links to be confusing in the table of contents. Instead,
47+
ensure that a reference is included in the descriptive text.
48+
49+
API Change Notes
50+
^^^^^^^^^^^^^^^^
51+
52+
.. include:: ../api/next_api_changes/README.rst
53+
:start-line: 5
54+
:end-line: 31
55+
56+
What's new
57+
^^^^^^^^^^
58+
59+
.. include:: ../users/next_whats_new/README.rst
60+
:start-line: 5
61+
:end-line: 24
62+
63+
64+
Deprecation
65+
-----------
66+
67+
API changes in Matplotlib have to be performed following the deprecation process
68+
below, except in very rare circumstances as deemed necessary by the development
69+
team. This ensures that users are notified before the change will take effect
70+
and thus prevents unexpected breaking of code.
71+
72+
Rules
73+
^^^^^
74+
- Deprecations are targeted at the next point.release (e.g. 3.x)
75+
- Deprecated API is generally removed two point-releases after introduction
76+
of the deprecation. Longer deprecations can be imposed by core developers on
77+
a case-by-case basis to give more time for the transition
78+
- The old API must remain fully functional during the deprecation period
79+
- If alternatives to the deprecated API exist, they should be available
80+
during the deprecation period
81+
- If in doubt, decisions about API changes are finally made by the
82+
API consistency lead developer
83+
84+
.. _intro-deprecation:
85+
86+
Introduce deprecation
87+
^^^^^^^^^^^^^^^^^^^^^
88+
89+
#. Create :ref:`deprecation notice <api_whats_new>`
90+
91+
#. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
92+
deprecated API is used. There are a number of helper tools for this:
93+
94+
- Use ``_api.warn_deprecated()`` for general deprecation warnings
95+
- Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
96+
methods, or properties
97+
- Use ``@_api.deprecate_privatize_attribute`` to annotate deprecation of
98+
attributes while keeping the internal private version.
99+
- To warn on changes of the function signature, use the decorators
100+
``@_api.delete_parameter``, ``@_api.rename_parameter``, and
101+
``@_api.make_keyword_only``
102+
103+
All these helpers take a first parameter *since*, which should be set to
104+
the next point release, e.g. "3.x".
105+
106+
You can use standard rst cross references in *alternative*.
107+
108+
#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
109+
The general guideline is to match runtime reported behavior.
110+
111+
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
112+
are generally kept during the expiry period, and thus no changes are needed on
113+
introduction.
114+
- Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
115+
report the *new* (post deprecation) signature at runtime, and thus *should* be
116+
updated on introduction.
117+
- Items decorated with ``@_api.delete_parameter`` should include a default value hint
118+
for the deleted parameter, even if it did not previously have one (e.g.
119+
``param: <type> = ...``).
120+
121+
.. _expire-deprecation:
122+
123+
Expire deprecation
124+
^^^^^^^^^^^^^^^^^^
125+
126+
#. Create :ref:`deprecation announcement <api_whats_new>`. For the content,
127+
you can usually copy the deprecation notice and adapt it slightly.
128+
129+
#. Change the code functionality and remove any related deprecation warnings.
130+
131+
#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
132+
133+
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
134+
are to be removed on expiry.
135+
- Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
136+
will have been updated at introduction, and require no change now.
137+
- Items decorated with ``@_api.delete_parameter`` will need to be updated to the
138+
final signature, in the same way as the ``.py`` file signature is updated.
139+
- Any entries in :file:`ci/mypy-stubtest-allowlist.txt` which indicate a deprecation
140+
version should be double checked. In most cases this is not needed, though some
141+
items were never type hinted in the first place and were added to this file
142+
instead. For removed items that were not in the stub file, only deleting from the
143+
allowlist is required.
144+
145+
Adding new API and features
146+
---------------------------
147+
148+
Every new function, parameter and attribute that is not explicitly marked as
149+
private (i.e., starts with an underscore) becomes part of Matplotlib's public
150+
API. As discussed above, changing the existing API is cumbersome. Therefore,
151+
take particular care when adding new API:
152+
153+
- Mark helper functions and internal attributes as private by prefixing them
154+
with an underscore.
155+
- Carefully think about good names for your functions and variables.
156+
- Try to adopt patterns and naming conventions from existing parts of the
157+
Matplotlib API.
158+
- Consider making as many arguments keyword-only as possible. See also
159+
`API Evolution the Right Way -- Add Parameters Compatibly`__.
160+
161+
__ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters
162+
163+
164+
.. _versioning-directives:
165+
166+
Versioning directives
167+
---------------------
168+
169+
When making a backward incompatible change, please add a versioning directive in
170+
the docstring. The directives should be placed at the end of a description block.
171+
For example::
172+
173+
class Foo:
174+
"""
175+
This is the summary.
176+
177+
Followed by a longer description block.
178+
179+
Consisting of multiple lines and paragraphs.
180+
181+
.. versionadded:: 3.5
182+
183+
Parameters
184+
----------
185+
a : int
186+
The first parameter.
187+
b: bool, default: False
188+
This was added later.
189+
190+
.. versionadded:: 3.6
191+
"""
192+
193+
def set_b(b):
194+
"""
195+
Set b.
196+
197+
.. versionadded:: 3.6
198+
199+
Parameters
200+
----------
201+
b: bool
202+
203+
For classes and functions, the directive should be placed before the
204+
*Parameters* section. For parameters, the directive should be placed at the
205+
end of the parameter description. The patch release version is omitted and
206+
the directive should not be added to entire modules.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.