📝 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)

.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: