📝 Integrate Towncrier

[webknjaz]

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)

❓ What kind of change does this PR introduce?

• 🐞 bug fix
• 🐣 feature
• 📋 docs update
• 📋 tests/coverage improvement
• 📋 refactoring
• 💥 other

📋 What is the related issue number (starting with #)

N/A

❓ What is the current behavior? (You can also link to an open issue here)

The resulting changelog is crafted manually with titles produced by a custom in-repo directive that retrieves the date from Git dynamically.

❓ What is the new behavior (if this is a feature change)?

The changelog file is static. News fragments are to be enclosed with pull requests.

📋 Other information:

N/A

📋 Contribution checklist:

(If you're a first-timer, check out
this guide on making great pull requests)

• I wrote descriptive pull request text above
• I think the code is well written
• I wrote good commit messages
• I have squashed related commits together after
  the changes have been approved
• Unit tests for the changes exist
• Integration tests for the changes exist (if applicable)
• I used the same coding conventions as the rest of the project
• The new code doesn't generate linter offenses
• Documentation reflects the changes
• The PR relates to only one subject with a clear title
  and description in grammatically correct, complete sentences

---

This change is 

[codecov]

Codecov Report

Merging #654 (7940907) into main (a2388b7) will not change coverage.
Report is 2 commits behind head on main.
The diff coverage is n/a.

❗ Current head 7940907 differs from pull request most recent head f8babb3. Consider uploading reports for the commit f8babb3 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #654   +/-   ##
=======================================
  Coverage   83.58%   83.58%           
=======================================
  Files          28       28           
  Lines        4172     4172           
=======================================
  Hits         3487     3487           
  Misses        685      685