Skip to content

Commit

Permalink
doc: Use towncrier to handle release notes
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
wismill committed Mar 12, 2024
1 parent ddbefb6 commit 737706f
Show file tree
Hide file tree
Showing 6 changed files with 104 additions and 0 deletions.
File renamed without changes.
62 changes: 62 additions & 0 deletions changes/README.md
Original file line number Diff line number Diff line change
@@ -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
```
Empty file added changes/api/.gitignore
Empty file.
Empty file added changes/build/.gitignore
Empty file.
Empty file added changes/tools/.gitignore
Empty file.
42 changes: 42 additions & 0 deletions towncrier.toml
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 737706f

Please sign in to comment.