From 737706fe83f2e1e42e29585919d89920e017b1fc Mon Sep 17 00:00:00 2001
From: Pierre Le Marre <dev@wismill.eu>
Date: Thu, 7 Mar 2024 10:08:16 +0100
Subject: [PATCH] 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.
---
 NEWS => NEWS.md          |  0
 changes/README.md        | 62 ++++++++++++++++++++++++++++++++++++++++
 changes/api/.gitignore   |  0
 changes/build/.gitignore |  0
 changes/tools/.gitignore |  0
 towncrier.toml           | 42 +++++++++++++++++++++++++++
 6 files changed, 104 insertions(+)
 rename NEWS => NEWS.md (100%)
 create mode 100644 changes/README.md
 create mode 100644 changes/api/.gitignore
 create mode 100644 changes/build/.gitignore
 create mode 100644 changes/tools/.gitignore
 create mode 100644 towncrier.toml

diff --git a/NEWS b/NEWS.md
similarity index 100%
rename from NEWS
rename to NEWS.md
diff --git a/changes/README.md b/changes/README.md
new file mode 100644
index 000000000..4599cd229
--- /dev/null
+++ b/changes/README.md
@@ -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
+```
diff --git a/changes/api/.gitignore b/changes/api/.gitignore
new file mode 100644
index 000000000..e69de29bb
diff --git a/changes/build/.gitignore b/changes/build/.gitignore
new file mode 100644
index 000000000..e69de29bb
diff --git a/changes/tools/.gitignore b/changes/tools/.gitignore
new file mode 100644
index 000000000..e69de29bb
diff --git a/towncrier.toml b/towncrier.toml
new file mode 100644
index 000000000..fdf1b40b4
--- /dev/null
+++ b/towncrier.toml
@@ -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