From 439007114c190fb357255ff8f6be9a3ae5045ad4 Mon Sep 17 00:00:00 2001
From: Aurélien Bompard <aurelien@bompard.org>
Date: Jan 29 2019 14:30:13 +0000
Subject: Add towncrier


Signed-off-by: Aurélien Bompard <aurelien@bompard.org>

---

diff --git a/docs/dev-guide/documentation.rst b/docs/dev-guide/documentation.rst
index e5ed608..a008161 100644
--- a/docs/dev-guide/documentation.rst
+++ b/docs/dev-guide/documentation.rst
@@ -106,6 +106,61 @@ After that, all you need to do is use the ``autoflask`` ReStructuredText
 directive.
 
 
+Release Notes and ChangeLog
+===========================
+
+The release notes (or the changelog) can be managed using `towncrier`_. It can
+build a release notes files by assembling items that would be written in
+separate files by each pull request (or commit). This way, the different
+commits will not conflict by writing in the same changelog file, and a link to
+the issue, the pull request or the commit is automatically inserted.
+
+In your project root, add a ``pyproject.toml`` file with a ``tool.towncrier``
+section similar to the one in `fedora-messaging
+<https://raw.githubusercontent.com/fedora-infra/fedora-messaging/master/pyproject.toml>`_.
+
+Create a ``news`` directory where the news items will be written, and in there
+create a ``_template.rst`` file with a content similar to the one in
+`fedora-messaging
+<https://raw.githubusercontent.com/fedora-infra/fedora-messaging/master/news/_template.rst>`_.
+
+Of course, replace ``fedora_messaging`` and the project URL by yours, where applicable.
+
+Then create a ``docs/changelog.rst`` file (location configured in the ``pyproject.toml`` file) with the follwing content::
+
+   =============
+   Release Notes
+   =============
+
+   .. towncrier release notes start
+
+Then each commit can add a file in the ``news`` folder to document the change.
+The file has the ``source.type`` name format, where ``type`` is one of:
+
+* ``feature``: for new features
+* ``bug``: for bug fixes
+* ``api``: for API changes
+* ``dev``: for development-related changes
+* ``author``: for contributor names
+* ``other``: for other changes
+
+And where the ``source`` part of the filename is:
+
+* ``42`` when the change is described in issue ``42``
+* ``PR42`` when the change has been implemented in pull request ``42``, and
+  there is no associated issue
+* ``Cabcdef`` when the change has been implemented in changeset ``abcdef``, and
+  there is no associated issue or pull request.
+* ``username`` for contributors (``author`` extention). It should be the
+  username part of their commits' email address.
+
+A preview of the release notes can be generated with ``towncrier --draft``.
+
+When running ``towncrier``, the tool will write the changelog file and remove
+the individual news fragments. These changes can then be committed as part of
+the release commit.
+
+.. _towncrier: https://pypi.org/project/towncrier/
 .. _Sphinx: http://www.sphinx-doc.org/
 .. _Google style: http://www.sphinx-doc.org/en/1.5.2/ext/example_google.html
 .. _NumPy style: http://www.sphinx-doc.org/en/1.5.2/ext/example_numpy.html