📝 Integrate Towncrier

This allows tracking change log entries within pull requests.

Below is the script used to convert the old semi-dynamic changelog
format into a static one:

    #! /usr/bin/env python3

    import subprocess

    from pathlib import Path
    from re import sub as _re_replace

    from dateutil.parser import parse as parse_timestamp

    def _get_scm_timestamp_for(committish):
        """Retrieve the tag date from SCM."""
        try:
            ts = subprocess.check_output(
                ('git', 'log', '-1', '--format=%aI', committish),
                stderr=subprocess.DEVNULL,
                text=True,
            ).strip()
        except subprocess.SubprocessError:
            raise ValueError(
                f'There is no `{committish}` in Git',
            ) from None

        return parse_timestamp(ts)

    def _retrieve_release_date(version_tag):
        try:
            version_date = _get_scm_timestamp_for(version_tag)
        except (ValueError, RuntimeError):
            return 'no Git tag matched'
        else:
            return f'{version_date:%Y-%m-%d}'

    changes_rst_path = Path('CHANGES.rst')
    changes_rst_txt = changes_rst_path.read_text()

    def _replace_version(ver_match_obj) -> str:
        version_str = ver_match_obj.group('version_string')
        prefixed_version_str = f'v{version_str !s}'
        release_date = _retrieve_release_date(prefixed_version_str)
        return f'{prefixed_version_str !s}\n{"=" * len(prefixed_version_str)}\n\n*({release_date !s})*'

    replaced_changes_rst_txt = _re_replace(r'.. scm-version-title:: v(?P<version_string>\d+.\d+.\d+)', _replace_version, changes_rst_txt)
    changes_rst_path.write_text(replaced_changes_rst_txt)

.github/CONTRIBUTING.rst

@@ -1,13 +1,14 @@
-Read and contribute to Cheroot
-------------------------------
+=========================
+Contributing to |project|
+=========================
 
 Make sure you read the `README
 <https://github.com/cherrypy/cheroot/blob/master/README.rst>`_.
 Also **ensure you set up pre-commit utility correctly** and
 tests pass in GitHub Actions CI/CD workflows.
 
 Submitting Pull Requests
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 If you're changing the structure of the repository please create an issue
 first. Don't forget to write appropriate test cases, add them into CI process
 if applicable and make the GitHub Actions CI/CD build pass.
@@ -16,7 +17,7 @@ Sync (preferably rebase) your feature branch with upstream regularly to make
 us able to merge your PR seamlessly.
 
 Submitting bug reports
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Make sure you are on latest changes and that you re-ran this command ``tox``
 after updating your local repository. If you can, please provide more
@@ -25,6 +26,6 @@ python version, and any other related software versions. It is also helpful to
 post a markdown snippet demonstrating minimum reproducible example of an issue.
 
 Also
-----
+^^^^
 See `Contributing <https://docs.cherrypy.dev/en/latest/contribute.html>`_ in
 the CherryPy docs.

.pre-commit-config.yaml

@@ -6,6 +6,56 @@ ci:
   - stubtest
 
 repos:
+- repo: local
+  hooks:
+  - id: changelogs-rst
+    name: changelog filenames
+    language: fail
+    entry: >-
+      Changelog files must be named
+      ####.(
+      bugfix
+      | feature
+      | deprecation
+      | breaking
+      | doc
+      | packaging
+      | contrib
+      | misc
+      )(.#)?(.rst)?
+    exclude: >-
+      (?x)
+      ^
+        docs/changelog-fragments.d/(
+          \.gitignore
+          |(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40})\.(
+            bugfix
+            |feature
+            |deprecation
+            |breaking
+            |doc
+            |packaging
+            |contrib
+            |misc
+          )(\.\d+)?(\.rst)?
+          |README\.rst
+          |\.towncrier-template\.rst\.j2
+        )
+      $
+    files: ^docs/changelog-fragments\.d/
+    types: []
+    types_or:
+    - file
+    - symlink
+  - id: changelogs-user-role
+    name: Changelog files should use a non-broken :user:`name` role
+    language: pygrep
+    entry: :user:([^`]+`?|`[^`]+[\s,])
+    pass_filenames: true
+    types:
+    - file
+    - rst
+
 - repo: https://github.com/asottile/add-trailing-comma.git
   rev: v3.0.0
   hooks:
@@ -27,7 +77,9 @@ repos:
   - id: rst-linter
     exclude: >-
       (?x)
-      CHANGES.rst
+      \.github/CONTRIBUTING\.rst
+      |
+      CHANGES\.rst
       |
       docs/
     files: >-