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.
This commit is contained in:
1 parent
ddbefb6760
commit
737706fe83
6 files changed
+104
No files matched your search
File renamed without changes.
@@ -0,0 +1,62 @@
|
||||
# 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 3 news fragments types:
|
||||
|
||||
- Breaking changes: `.breaking`
|
||||
- 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
|
||||
```
|
||||
Whitespace-only changes.
Whitespace-only changes.
Whitespace-only changes.
@@ -0,0 +1,42 @@
|
||||
[tool.towncrier]
|
||||
name = "libxkbcommon"
|
||||
directory = "changes"
|
||||
filename = "NEWS.md"
|
||||
start_string = "<!-- towncrier release notes start -->\n"
|
||||
all_bullets = true
|
||||
single_file = true
|
||||
orphan_prefix = "+"
|
||||
underlines = ["=", "-", ""]
|
||||
title_format = "{name} [{version}](https://github.com/xkbcommon/libxkbcommon/tree/xkbcommon-{version}) - {project_date}"
|
||||
issue_format = "[#{issue}](https://github.com/xkbcommon/libxkbcommon/issues/{issue})"
|
||||
|
||||
# Sections configuration
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "API"
|
||||
path = "api"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Tools"
|
||||
path = "tools"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Build system"
|
||||
path = "build"
|
||||
|
||||
# Fragments configuration
|
||||
|
||||
[[tool.towncrier.type]]
|
||||
directory = "breaking"
|
||||
name = "Breaking changes"
|
||||
showcontent = true
|
||||
|
||||
[[tool.towncrier.type]]
|
||||
directory = "feature"
|
||||
name = "New"
|
||||
showcontent = true
|
||||
|
||||
[[tool.towncrier.type]]
|
||||
directory = "bugfix"
|
||||
name = "Fixes"
|
||||
showcontent = true
|
||||
Reference in new issue
Block a user