Use towncrier to generate a user centric changelog from news fragments

changelog/README.rst

@@ -0,0 +1,32 @@
+This directory contains "newsfragments" which are short files that contain a small **ReST**-formatted
+text that will be added to the next ``CHANGELOG``.
+
+The ``CHANGELOG`` will be read by users, so this description should be aimed to radish users
+instead of describing internal changes which are only relevant to the developers.
+
+Make sure to use full sentences with correct case and punctuation, for example::
+
+    Fix issue with non-ascii messages from the ``warnings`` module.
+
+Each file should be named like ``<ISSUE>.<TYPE>``, where
+``<ISSUE>`` is an issue number, and ``<TYPE>`` is one of:
+
+* ``feature``: new user facing features, like new command-line options and new behavior.
+* ``bugfix``: fixes a reported bug.
+* ``doc``: documentation improvement, like rewording an entire session or adding missing docs.
+* ``removal``: feature removal.
+
+So for example: ``123.feature``, ``456.bugfix``.
+
+If your PR fixes an issue, use that number here. If there is no issue,
+then after you submit the PR and get the PR number you can add a
+changelog using that instead.
+
+If you are not sure what issue type to use, don't hesitate to ask in your PR.
+
+``towncrier`` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries
+other than ``features`` it is usually better to stick to a single paragraph to keep it concise.
+You can install ``towncrier`` and then run ``towncrier --draft``
+if you want to get a preview of how your change will look in the final release notes.
+
+Disclaimer: this README was copied and adapted to the need of radish from the awesome pytest project.

changelog/template.rst

@@ -0,0 +1,39 @@
+{% for section in sections %}
+{% set underline = "-" %}
+{% if section %}
+{{section}}
+{{ underline * section|length }}{% set underline = "~" %}
+
+{% endif %}
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section] %}
+
+{{ definitions[category]['name'] }}
+{{ underline * definitions[category]['name']|length }}
+
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category]|dictsort(by='value') %}
+- {{ text }}{% if category != 'vendor' %} ({{ values|sort|join(', ') }}){% endif %}
+
+
+{% endfor %}
+{% else %}
+- {{ sections[section][category]['']|sort|join(', ') }}
+
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+
+No significant changes.
+
+
+{% else %}
+{% endif %}
+{% endfor %}
+{% else %}
+
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

pyproject.toml

@@ -1,3 +1,11 @@
 [tool.black]
 target_version = ["py37"]
 include = "(setup.py|src|tests)"
+
+[tool.towncrier]
+package = "radish"
+package_dir = "src"
+filename = "CHANGELOG.rst"
+directory = "changelog/"
+title_format = "radish-bdd {version} ({project_date})"
+template = "changelog/template.rst"

setup.py

@@ -49,7 +49,7 @@
     "tests": ["freezegun", "coverage", "pytest", "pytest-mock"],
 }
 EXTRAS_REQUIRES["dev"] = (
-    EXTRAS_REQUIRES["tests"] + EXTRAS_REQUIRES["docs"] + ["pre-commit"]
+    EXTRAS_REQUIRES["tests"] + EXTRAS_REQUIRES["docs"] + ["pre-commit", "towncrier"]
 )
 
 #: Holds the contents of the README file