Skip to content

Commit dc5d794

Browse 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 dc5d794

File tree

7 files changed

+981
-918
lines changed

7 files changed

+981
-918
lines changed

‎doc/devel/api_changes.rst

+206
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)