1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
# Fragments for the changelog
This directory contains fragments for the future [NEWS](../NEWS.md) file.
## Introduction
We use <code>[towncrier]</code> to produce useful, summarized news files.
There are 3 sections types:
- API: `changes/api`
- Tools: `changes/tools`
- Build System: `changes/build`
There are 4 news fragments types:
- Breaking changes: `.breaking`
- Deprecated: `.deprecated`
- New: `.feature`
- Fixes: `.bugfix`
[towncrier]: https://pypi.org/project/towncrier/
## Adding a fragment
Add a short description of the change in a file `changes/SECTION/ID.FRAGMENT.md`,
where:
- `SECTION` and `FRAGMENT` values are described in the [previous section](#introduction).
- `ID` is the corresponding issue identifier on Github, if relevant. If there is
no such issue, then `ID` should start with `+` and some identifier that make
the file unique in the directory.
Examples:
- A _bug fix_ for the _issue #463_ is an _API_ change, so the corresponding file
should be named `changes/api/463.bugfix.md`.
- A _new feature_ for _tools_ like #448 corresponds to e.g.
`changes/tools/+add-verbose-opt.feature.md`.
Guidelines for the fragment files:
- Use the [Markdown] markup.
- Use past tense, e.g. “Fixed a segfault”.
- Look at the previous releases [NEWS](../NEWS.md) file for further examples.
[Markdown]: https://daringfireball.net/projects/markdown/
## Build the changelog
Install <code>[towncrier]</code> from Pypi:
```bash
python3 -m pip install towncrier
```
Then build the changelog:
```bash
# Only check the result. Useful after adding a new fragment.
towncrier build --draft --version 1.8.0
# Write the changelog & delete the news fragments
towncrier build --yes --version 1.8.0
```
|
