README.rst
1:orphan:
2
3Changelog
4=========
5
6This directory contains "news fragments" which are short files that contain a
7small **ReST**-formatted text that will be added to the next what's new page.
8
9Make sure to use full sentences with correct case and punctuation, and please
10try to use Sphinx intersphinx using backticks. The fragment should have a
11header line and an underline using ``------``
12
13Each file should be named like ``<PULL REQUEST>.<TYPE>.rst``, where
14``<PULL REQUEST>`` is a pull request number, and ``<TYPE>`` is one of:
15
16* ``new_function``: New user facing functions.
17* ``deprecation``: Changes existing code to emit a DeprecationWarning.
18* ``future``: Changes existing code to emit a FutureWarning.
19* ``expired``: Removal of a deprecated part of the API.
20* ``compatibility``: A change which requires users to change code and is not
21 backwards compatible. (Not to be used for removal of deprecated features.)
22* ``c_api``: Changes in the Numpy C-API exported functions
23* ``new_feature``: New user facing features like ``kwargs``.
24* ``improvement``: General improvements and edge-case changes which are
25 not new features or compatibility related.
26* ``performance``: Performance changes that should not affect other behaviour.
27* ``change``: Other changes
28* ``highlight``: Adds a highlight bullet point to use as a possibly highlight
29 of the release.
30
31It is possible to add two files with different categories (and text) if both
32are relevant. For example a change may improve performance but have some
33compatibility concerns.
34
35Most categories should be formatted as paragraphs with a heading.
36So for example: ``123.new_feature.rst`` would have the content::
37
38 ``my_new_feature`` option for `my_favorite_function`
39 ----------------------------------------------------
40 The ``my_new_feature`` option is now available for `my_favorite_function`.
41 To use it, write ``np.my_favorite_function(..., my_new_feature=True)``.
42
43``highlight`` is usually formatted as bulled points making the fragment
44``* This is a highlight``.
45
46Note the use of single-backticks to get an internal link (assuming
47``my_favorite_function`` is exported from the ``numpy`` namespace),
48and double-backticks for code.
49
50If you are unsure what pull request type to use, don't hesitate to ask in your
51PR.
52
53You can install ``towncrier`` and run ``towncrier build --draft --version 1.18``
54if you want to get a preview of how your change will look in the final release
55notes.
56
57.. note::
58
59 This README was adapted from the pytest changelog readme under the terms of
60 the MIT licence.
61
62