🐛 fix(release): format generated changelog (#1170)

Format the generated changelog with [docstrfmt
2.2.1](https://github.com/LilSpazJoekp/docstrfmt/releases/tag/v2.2.1)
before creating a release commit. v2.2.0 skipped `CHANGELOG.rst` in
GitHub's `build/build` checkout, leaving the 1.6.0 changelog over 120
columns.

Pin the release dependency and pre-commit hook to v2.2.1, with a
package-specific cutoff timestamp so uv can install it before the
seven-day window expires. Reformat the existing changelog to match
docstrfmt's output.

Author: gaborbernat

.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
           - mdformat-gfm>=1
           - mdformat-ruff>=0.1.3
   - repo: https://github.com/LilSpazJoekp/docstrfmt
-    rev: a05381030e526dc863e2006d34824271d7681d08 # frozen: v2.2.0
+    rev: c1813841673cdcd6cf602dde1edb78a5d5e45235 # frozen: v2.2.1
     hooks:
       - id: docstrfmt
         args: ["-l", "120"]

CHANGELOG.rst

@@ -12,38 +12,39 @@
   :user:`gaborbernat` (:issue:`311`)
 - The "Unmet dependencies" error from ``--no-isolation`` builds now shows the wanted version, found version, and
   interpreter - by :user:`gaborbernat` (:issue:`504`)
-- Add ``--sdist-extract-dir`` to extract the intermediate sdist into a persistent directory, enabling compiler cache reuse
-  across rebuilds - by :user:`gaborbernat` (:issue:`614`)
-- Add ``--env-dir`` to place the isolated build environment at a fixed path, enabling compiler cache reuse across builds -
-  by :user:`gaborbernat` (:issue:`655`)
+- Add ``--sdist-extract-dir`` to extract the intermediate sdist into a persistent directory, enabling compiler cache
+  reuse across rebuilds - by :user:`gaborbernat` (:issue:`614`)
+- Add ``--env-dir`` to place the isolated build environment at a fixed path, enabling compiler cache reuse across builds
+  - by :user:`gaborbernat` (:issue:`655`)
 - Print a summary of resolved dependency versions (``name==version``) after installing them in isolated builds - by
   :user:`gaborbernat` (:issue:`959`)
-- On build failure, print a tip pointing to ``--env-dir`` and ``--sdist-extract-dir`` for debugging and link to the "Debug
-  a failed build" how-to - reported by :user:`dimpase`, implemented by :user:`gaborbernat` (:issue:`966`)
+- On build failure, print a tip pointing to ``--env-dir`` and ``--sdist-extract-dir`` for debugging and link to the
+  "Debug a failed build" how-to - reported by :user:`dimpase`, implemented by :user:`gaborbernat` (:issue:`966`)
 
 **********
  Bugfixes
 **********
 
 - Drain verbose subprocess output inline instead of using a ``ThreadPoolExecutor``, which silently swallowed logging
   errors - by :user:`henryiii` (:issue:`1098`)
-- Reject a file passed as ``--env-dir`` with a clear error instead of a raw ``FileExistsError`` - by :user:`henryiii` (:issue:`1100`)
+- Reject a file passed as ``--env-dir`` with a clear error instead of a raw ``FileExistsError`` - by :user:`henryiii`
+  (:issue:`1100`)
 - Emit CLI warnings to stderr instead of stdout, so they no longer corrupt ``--metadata`` JSON output on stdout - by
   :user:`ymyzk` (:issue:`1111`)
-- Fix the Windows symlink support probe always returning ``False`` due to a stale object interpolated into the destination
-  path - by :user:`henryiii` (:issue:`1118`)
+- Fix the Windows symlink support probe always returning ``False`` due to a stale object interpolated into the
+  destination path - by :user:`henryiii` (:issue:`1118`)
 - Fix ``metadata_path``'s build-backend fallback returning a nonexistent dist-info path for wheels with a build tag - by
   :user:`henryiii` (:issue:`1119`)
-- Write pip/uv requirements and constraints files with ``\n`` instead of ``os.linesep``, avoiding doubled ``\r\r\n`` line
-  endings on Windows - by :user:`henryiii` (:issue:`1120`)
+- Write pip/uv requirements and constraints files with ``\n`` instead of ``os.linesep``, avoiding doubled ``\r\r\n``
+  line endings on Windows - by :user:`henryiii` (:issue:`1120`)
 - Batch of small robustness fixes: correct macOS release parsing for the minimum pip version, avoid sharing the mutable
   default build-system table between builders, keep the original error when isolated-environment setup fails early, and
   raise ``BuildException`` for an invalid wheel - by :user:`henryiii` (:issue:`1121`)
 - Decide color support independently for stdout and stderr instead of only checking ``stdout.isatty()``, so redirecting
   one stream no longer disables or leaks ANSI colors on the other - by :user:`henryiii` (:issue:`1123`)
 - Pass ``--dependency-constraints-txt`` files through to the installer unmodified instead of re-parsing them into a
-  deduplicated set of lines, fixing a case where a hashed requirement (e.g. from ``pip-compile --generate-hashes``) could
-  have its ``--hash`` continuation line separated from its requirement line and silently dropped, depending on the
+  deduplicated set of lines, fixing a case where a hashed requirement (e.g. from ``pip-compile --generate-hashes``)
+  could have its ``--hash`` continuation line separated from its requirement line and silently dropped, depending on the
   interpreter's hash seed - by :user:`manfred-kaiser` (:issue:`1140`)
 
 **********
@@ -56,15 +57,17 @@
  Deprecations
 **************
 
-- Deprecate :func:`build.util.project_wheel_metadata`; use ``python -m build --metadata`` instead - by :user:`gaborbernat` (:issue:`557`)
-- Warn on config settings without a value (e.g. ``-C--my-flag``); use ``-C--my-flag=`` instead for compatibility with pip
-  - by :user:`gaborbernat` (:issue:`640`)
+- Deprecate :func:`build.util.project_wheel_metadata`; use ``python -m build --metadata`` instead - by
+  :user:`gaborbernat` (:issue:`557`)
+- Warn on config settings without a value (e.g. ``-C--my-flag``); use ``-C--my-flag=`` instead for compatibility with
+  pip - by :user:`gaborbernat` (:issue:`640`)
 
 ***************
  Miscellaneous
 ***************
 
-- :issue:`1058`, :issue:`1060`, :issue:`1062`, :issue:`1093`, :issue:`1099`, :issue:`1107`, :issue:`1113`, :issue:`1117`, :issue:`1122`, :issue:`1124`, :issue:`1128`, :issue:`1132`
+- :issue:`1058`, :issue:`1060`, :issue:`1062`, :issue:`1093`, :issue:`1099`, :issue:`1107`, :issue:`1113`,
+  :issue:`1117`, :issue:`1122`, :issue:`1124`, :issue:`1128`, :issue:`1132`
 
 ####################
  1.5.0 (2026-04-30)

docs/changelog/1170.misc.rst

@@ -0,0 +1 @@
+Format generated release changelogs with docstrfmt 2.2.1 and reformat the 1.6.0 changelog - by :user:`gaborbernat`

pyproject.toml

@@ -122,7 +122,7 @@ pyrefly = [
   { include-group = "typing" },
 ]
 release = [
-  "docstrfmt == 2.2.0", # keep in sync with the docstrfmt rev in .pre-commit-config.yaml
+  "docstrfmt == 2.2.1", # keep in sync with the docstrfmt rev in .pre-commit-config.yaml
   "gitpython >= 3.1.44",
   "packaging >= 25",
   "pre-commit >= 3.0",
@@ -147,6 +147,7 @@ exclude = [
 
 [tool.uv]
 exclude-newer = "7 days"
+exclude-newer-package = { docstrfmt = "2026-08-28T18:00:18Z" }
 
 
 [tool.coverage]

tasks/release.py

@@ -81,9 +81,7 @@ def create_release_commit(repo: Repo, version: Version) -> Commit:
     update_version_file(version)
     print('build changelog from fragments with towncrier')
     check_call(['towncrier', 'build', '--yes', '--version', version.public], cwd=str(ROOT_SRC_DIR))  # noqa: S603
-    # towncrier appends the issue reference past docstrfmt's width budget, so its raw output can run over the
-    # limit; reflow it here with a pinned docstrfmt instead of trusting the release job's isolated hook env,
-    # which passed over-long lines into 1.5.1 and left a changelog that failed pre-commit everywhere else.
+    # towncrier can append issue references past docstrfmt's width budget.
     check_call(['docstrfmt', '--line-length', '120', 'CHANGELOG.rst'], cwd=str(ROOT_SRC_DIR))
     call(['pre-commit', 'run', '--all-files'], cwd=str(ROOT_SRC_DIR))
     call(['pre-commit', 'run', '--all-files'], cwd=str(ROOT_SRC_DIR))