|
3 | 3 | Adding API change notes |
4 | 4 | ======================= |
5 | 5 |
|
6 | | -Please place new portions of `api_changes.rst`in the |
7 | | -`next_api_changes` directory. |
| 6 | +API change notes for future releases are collectedin the directory |
| 7 | +:file:`next_api_changes`. They are divided into four categories: |
8 | 8 |
|
9 | | -When adding an entry please look at the currently existing files to |
10 | | -see if you can extend any of them. If you create a file, name it |
11 | | -:file:`what_api_changes.rst` (ex:file:`deprecated_rcparams.rst`) with |
12 | | -contents following the form: :: |
| 9 | +- **Deprecations**: Announcements of future changes. Typically, these will |
| 10 | + raise a deprecation warning and users of this API should change their code |
| 11 | + to stay compatible with future releases of Matplotlib. If possible, state |
| 12 | + what should be used instead. |
| 13 | +- **Removals**: Parts of the API that got removed. If possible, state what |
| 14 | + should be used instead. |
| 15 | +- **Behaviour changes**: API that stays valid but will yield a different |
| 16 | + result. |
| 17 | +- **Development changes**: Changes to the build process, dependencies, etc. |
13 | 18 |
|
14 | | - Brief description of change |
15 | | - --------------------------- |
| 19 | +Please place new entries in the respective files in this directory. Typically, |
| 20 | +each change will get its own section, but you may also amend existing sections |
| 21 | +when suitable. The overall goal is a comprehensible documentation of the |
| 22 | +changes. |
16 | 23 |
|
17 | | - Long description of change, justification, and work-arounds to |
18 | | - maintain old behavior (if any). |
| 24 | +A typical entry could look like this:: |
19 | 25 |
|
| 26 | + Locators |
| 27 | + ~~~~~~~~ |
| 28 | + The unused `Locator.autoscale()` method is deprecated (pass the axis |
| 29 | + limits to `Locator.view_limits()` instead). |
20 | 30 |
|
21 | | -If you need more heading levels, please use ``~~~~`` and ``++++``. |
|