Skip to content

Commit 2cccb72

Browse files
committed
doc: Use towncrier to handle release notes
Towncrier is a utility to produce useful, summarized news files. See: - https://pypi.org/project/towncrier/ - https://towncrier.readthedocs.io Custom configuration for xkbcommon: - New fragments are located in the `changes` directory. - 3 sections: - API: `changes/api` - Tools: `changes/tools` - Build System: `changes/build` - 3 news fragments: - Breaking changes: `.breaking` - New: `.feature` - Fixes: `.bugfix` `NEWS` is renamed to `NEWS.md` because the tool requires `.md` extension to write in markdown format.
1 parent ba76ec1 commit 2cccb72

File tree

6 files changed

+104
-0
lines changed

6 files changed

+104
-0
lines changed

NEWS NEWS.md

File renamed without changes.

changes/README.md

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

changes/api/.gitignore

Whitespace-only changes.

changes/build/.gitignore

Whitespace-only changes.

changes/tools/.gitignore

Whitespace-only changes.

towncrier.toml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[tool.towncrier]
2+
name = "libxkbcommon"
3+
directory = "changes"
4+
filename = "NEWS.md"
5+
start_string = "<!-- towncrier release notes start -->\n"
6+
all_bullets = true
7+
single_file = true
8+
orphan_prefix = "+"
9+
underlines = ["=", "-", ""]
10+
title_format = "{name} [{version}](https://github.com/xkbcommon/libxkbcommon/tree/xkbcommon-{version}) - {project_date}"
11+
issue_format = "[#{issue}](https://github.com/xkbcommon/libxkbcommon/issues/{issue})"
12+
13+
# Sections configuration
14+
15+
[[tool.towncrier.section]]
16+
name = "API"
17+
path = "api"
18+
19+
[[tool.towncrier.section]]
20+
name = "Tools"
21+
path = "tools"
22+
23+
[[tool.towncrier.section]]
24+
name = "Build system"
25+
path = "build"
26+
27+
# Fragments configuration
28+
29+
[[tool.towncrier.type]]
30+
directory = "breaking"
31+
name = "Breaking changes"
32+
showcontent = true
33+
34+
[[tool.towncrier.type]]
35+
directory = "feature"
36+
name = "New"
37+
showcontent = true
38+
39+
[[tool.towncrier.type]]
40+
directory = "bugfix"
41+
name = "Fixes"
42+
showcontent = true

0 commit comments

Comments
 (0)