🧪🎨 Enforce empty trivial change notes

.git-blame-ignore-revs

@@ -34,3 +34,4 @@ c7ee560e00b85f7486b452c14ff49e4737996eda  # Blacken tools/
 94999255d5ede440c37137d210666fdf64302e75  # Reformat the codebase, with black
 585037a80a1177f1fa92e159a7079855782e543e  # Cleanup implicit string concatenation
 8a6f6ac19b80a6dc35900a47016c851d9fcd2ee2  # Blacken src/pip/_internal/resolution directory
+3303cd1ce4fa3a0b4fb6f4c300408ba523a6bb52  # 🤖 Reflow Towncrier categories list in config

.pre-commit-config.yaml

@@ -65,9 +65,73 @@ repos:
   - id: news-fragment-filenames
     name: NEWS fragment
     language: fail
-    entry: NEWS fragment files must be named *.(process|removal|feature|bugfix|vendor|doc|trivial).rst
-    exclude: ^news/(.gitignore|.*\.(process|removal|feature|bugfix|vendor|doc|trivial).rst)
+    entry: >-
+      NEWS fragment files must be named
+      ####.(
+      removal
+      |feature
+      |bugfix
+      |vendor
+      |doc
+      |packaging
+      |contrib
+      |misc
+      |trivial
+      )(.#)?(.rst)?
+    exclude: >-
+      (?x)
+      ^
+        news/(
+          \.gitignore
+          |(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40}|\+[^.]+)\.(
+            removal
+            |feature
+            |bugfix
+            |vendor
+            |doc
+            |packaging
+            |contrib
+            |misc
+            |trivial
+          )(\.\d+)?(\.rst)?
+          |[0-9a-zA-Z-_]+\.vendor(\.\d+)?(\.rst)?  # special-case vendoring
+          |README\.rst
+          |\.towncrier-template\.rst\.j2
+        )
+      $
     files: ^news/
+    types: []
+    types_or:
+    - file
+    - symlink
+  - id: trivial-news-fragment-empty
+    name: Trivial NEWS fragments must be empty
+    language: python
+    entry: >-
+      python3 -Ic 'import pathlib, sys;
+      trivial_notes = map(pathlib.Path, sys.argv[1:]);
+
+      non_empty_notes = [
+        note for note in trivial_notes
+        if note.lstat().st_size
+      ];
+      some_notes_are_non_empty = bool(len(non_empty_notes));
+
+      some_notes_are_non_empty or sys.exit(0);
+
+      print(f"ERROR: the following change log fragments must be empty:");
+
+      print("\n\t* ".join(["", *map(str, non_empty_notes)]));
+
+      print();
+
+      sys.exit(1)
+      '
+    files: ^news/[^.]+\.trivial.*$
+    types: []
+    types_or:
+    - file
+    - symlink
 
 ci:
   autofix_prs: false

docs/html/development/contributing.rst

@@ -110,8 +110,8 @@ public is concerned, typo fixes, white space modification, etc. To mark a PR
 as trivial a contributor simply needs to add a randomly named, empty file to
 the ``news/`` directory with the extension of ``.trivial.rst``. If you are on a
 POSIX like operating system, one can be added by running
-``touch news/$(uuidgen).trivial.rst``. On Windows, the same result can be
-achieved in Powershell using ``New-Item "news/$([guid]::NewGuid()).trivial.rst"``.
+``touch news/+$(uuidgen).trivial.rst``. On Windows, the same result can be
+achieved in Powershell using ``New-Item "news/+$([guid]::NewGuid()).trivial.rst"``.
 Core committers may also add a "skip news" label to the PR which will accomplish
 the same thing.
 
@@ -126,6 +126,25 @@ otherwise notable can be done using a ``news/<name>.process.rst`` file. This is
 not typically used, but can be used for things like changing version schemes,
 updating deprecation policy, etc.
 
+Changes to the packaging metadata and tooling of pip itself should be documented
+in :file:`news/{<name>}.packaging.rst` files. This can include notes for
+downstreams about unobvious side effects and tooling, as well as changes in the
+test invocation considerations and runtime assumptions.
+
+When your change is something that influence how contributors and core
+committers interact with the project, record that and actionable updates via a
+:file:`news/{<name>}.contrib.rst` file. Stuff that affects the contributor
+experience, like running tests, building the docs, setting up the development
+environment would go here. It's useful for occasional contributors to learn the
+gist of what's changed since the last time they were active.
+
+If you feel like that your change would affect the end-users in noticeable ways
+but it's difficult to assign any of the above categories to it, it is possible
+to add a :file:`news/{<name>}.misc.rst` file to still present the change's
+effect in the change log. Unlike :file:`news/{<name>}.trivial.rst` entries, this
+change log fragment type will show up publicly in the released change log
+document.
+
 
 Updating your branch
 ====================

news/.gitignore

@@ -1 +1,29 @@
+*
 !.gitignore
+!*.bugfix
+!*.bugfix.rst
+!*.bugfix.*.rst
+!*.contrib
+!*.contrib.rst
+!*.contrib.*.rst
+!*.doc
+!*.doc.rst
+!*.doc.*.rst
+!*.feature
+!*.feature.rst
+!*.feature.*.rst
+!*.misc
+!*.misc.rst
+!*.misc.*.rst
+!*.packaging
+!*.packaging.rst
+!*.packaging.*.rst
+!*.removal
+!*.removal.rst
+!*.removal.*.rst
+!*.trivial
+!*.trivial.rst
+!*.trivial.*.rst
+!*.trivial
+!*.vendor.rst
+!*.vendor.*.rst

news/12555.contrib.rst

@@ -0,0 +1 @@
+12853.contrib.rst

news/12853.contrib.rst

@@ -0,0 +1,7 @@
+Added separate changelog fragment types for contributor-
+and downstream-facing patches, as well as a catch-all
+miscellaneous section.
+
+Their corresponding identifiers are ``contrib`` and ``packaging``
+respectively. They are meant to be used for more accurate
+classification, where one would resort to using ``misc`` otherwise.

news/12854.contrib.rst

@@ -0,0 +1,2 @@
+The pre-commit linting suite now makes sure that any change
+notes labeled as ``trivial`` are empty.

news/setuptools.vendor.rst

@@ -1 +1,4 @@
 Upgrade setuptools to 70.3.0
+
+Additionally, remove the suppressed deprecation warning from the vendored
+``pkg_resources`` copy to ensure builds succeed with ``PYTHONWARNINGS=error``.

pyproject.toml

@@ -89,13 +89,25 @@ template = "tools/news/template.rst"
 
 # Grouping of entries, within our changelog
 type = [
-  { name = "Deprecations and Removals", directory = "removal", showcontent = true },
-  { name = "Features",                  directory = "feature", showcontent = true },
-  { name = "Bug Fixes",                 directory = "bugfix",  showcontent = true },
-  { name = "Vendored Libraries",        directory = "vendor",  showcontent = true },
-  { name = "Improved Documentation",    directory = "doc",     showcontent = true },
-  { name = "Process",                   directory = "process", showcontent = true },
-  { name = "Trivial Changes",           directory = "trivial", showcontent = false },
+  { name = "Deprecations and Removals",                   directory = "removal",   showcontent = true },
+  { name = "Features",                                    directory = "feature",   showcontent = true },
+  { name = "Bug Fixes",                                   directory = "bugfix",    showcontent = true },
+  { name = "Vendored Libraries",                          directory = "vendor",    showcontent = true },
+  { name = "Improved Documentation",                      directory = "doc",       showcontent = true },
+
+  # Notes for downstreams about unobvious side effects and tooling. Changes
+  # in the test invocation considerations and runtime assumptions.
+  { name = "Packaging updates and notes for downstreams", directory = "packaging", showcontent = true },
+
+  # Stuff that affects the contributor experience. e.g. Running tests,
+  # building the docs, setting up the development environment.
+  { name = "Contributor-facing changes",                  directory = "contrib",   showcontent = true },
+
+  # Changes that are hard to assign to any of the above categories.
+  { name = "Miscellaneous internal changes",              directory = "misc",      showcontent = true },
+
+  # A way for the contributors to fool the changelog fragment presence check.
+  { name = "Trivial Changes",                             directory = "trivial",   showcontent = false },
 ]
 
 ######################################################################################