Merge pull request #12501 from webknjaz/maintenance/changelog-categories

📝💅 Split trivial change log category into 3

.pre-commit-config.yaml

@@ -66,8 +66,41 @@ repos:
     -   id: changelogs-rst
         name: changelog filenames
         language: fail
-        entry: 'changelog files must be named ####.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst'
-        exclude: changelog/(\d+\.(breaking|bugfix|deprecation|doc|feature|improvement|trivial|vendor).rst|README.rst|_template.rst)
+        entry: >-
+          changelog files must be named
+          ####.(
+          breaking
+          | deprecation
+          | feature
+          | improvement
+          | bugfix
+          | vendor
+          | doc
+          | packaging
+          | contrib
+          | misc
+          )(.#)?(.rst)?
+        exclude: >-
+          (?x)
+          ^
+            changelog/(
+              \.gitignore
+              |\d+\.(
+                breaking
+                |deprecation
+                |feature
+                |improvement
+                |bugfix
+                |vendor
+                |doc
+                |packaging
+                |contrib
+                |misc
+              )(\.\d+)?(\.rst)?
+              |README\.rst
+              |_template\.rst
+            )
+          $
         files: ^changelog/
     -   id: py-deprecated
         name: py library is deprecated

changelog/.gitignore

@@ -0,0 +1,34 @@
+*
+!.gitignore
+!_template.rst
+!README.rst
+!*.bugfix
+!*.bugfix.rst
+!*.bugfix.*.rst
+!*.breaking
+!*.breaking.rst
+!*.breaking.*.rst
+!*.contrib
+!*.contrib.rst
+!*.contrib.*.rst
+!*.deprecation
+!*.deprecation.rst
+!*.deprecation.*.rst
+!*.doc
+!*.doc.rst
+!*.doc.*.rst
+!*.feature
+!*.feature.rst
+!*.feature.*.rst
+!*.improvement
+!*.improvement.rst
+!*.improvement.*.rst
+!*.misc
+!*.misc.rst
+!*.misc.*.rst
+!*.packaging
+!*.packaging.rst
+!*.packaging.*.rst
+!*.vendor
+!*.vendor.rst
+!*.vendor.*.rst

changelog/12501.contrib.rst

@@ -0,0 +1,11 @@
+The changelog configuration has been updated to introduce more accurate
+audience-tailored categories. Previously, there was a ``trivial``
+change log fragment type with an unclear and broad meaning. It was
+removed and we now have ``contrib``, ``misc`` and ``packaging`` in
+place of it.
+
+The new change note types target the readers who are downstream
+packagers and project contributors. Additionally, the miscellaneous
+section is kept for unspecified updates that do not fit anywhere else.
+
+-- by :user:`webknjaz`

changelog/README.rst

@@ -20,10 +20,22 @@ Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
 * ``deprecation``: feature deprecation.
 * ``breaking``: a change which may break existing suites, such as feature removal or behavior change.
 * ``vendor``: changes in packages vendored in pytest.
-* ``trivial``: fixing a small typo or internal change that might be noteworthy.
+* ``packaging``: notes for downstreams about unobvious side effects
+  and tooling. changes in the test invocation considerations and
+  runtime assumptions.
+* ``contrib``: stuff that affects the contributor experience. e.g.
+  Running tests, building the docs, setting up the development
+  environment.
+* ``misc``: changes that are hard to assign to any of the above
+  categories.
 
 So for example: ``123.feature.rst``, ``456.bugfix.rst``.
 
+.. tip::
+
+   See :file:`pyproject.toml` for all available categories
+   (``tool.towncrier.type``).
+
 If your PR fixes an issue, use that number here. If there is no issue,
 then after you submit the PR and get the PR number you can add a
 changelog using that instead.

pyproject.toml

@@ -372,44 +372,74 @@ directory = "changelog/"
 title_format = "pytest {version} ({project_date})"
 template = "changelog/_template.rst"
 
+# NOTE: The types are declared because:
+# NOTE: - there is no mechanism to override just the value of
+# NOTE:   `tool.towncrier.type.misc.showcontent`;
+# NOTE: - and, we want to declare extra non-default types for
+# NOTE:   clarity and flexibility.
+
 [[tool.towncrier.type]]
+# When something public gets removed in a breaking way. Could be
+# deprecated in an earlier release.
 directory = "breaking"
-name = "Breaking Changes"
+name = "Removals and backward incompatible breaking changes"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Declarations of future API removals and breaking changes in behavior.
 directory = "deprecation"
-name = "Deprecations"
+name = "Deprecations (removal in next major release)"
 showcontent = true
 
 [[tool.towncrier.type]]
+# New behaviors, public APIs. That sort of stuff.
 directory = "feature"
-name = "Features"
+name = "New features"
 showcontent = true
 
 [[tool.towncrier.type]]
+# New behaviors in existing features.
 directory = "improvement"
-name = "Improvements"
+name = "Improvements in existing functionality"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Something we deemed an improper undesired behavior that got corrected
+# in the release to match pre-agreed expectations.
 directory = "bugfix"
-name = "Bug Fixes"
+name = "Bug fixes"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Updates regarding bundling dependencies.
 directory = "vendor"
-name = "Vendored Libraries"
+name = "Vendored libraries"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Notable updates to the documentation structure or build process.
 directory = "doc"
-name = "Improved Documentation"
+name = "Improved documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+# Notes for downstreams about unobvious side effects and tooling. Changes
+# in the test invocation considerations and runtime assumptions.
+directory = "packaging"
+name = "Packaging updates and notes for downstreams"
+showcontent = true
+
+[[tool.towncrier.type]]
+# Stuff that affects the contributor experience. e.g. Running tests,
+# building the docs, setting up the development environment.
+directory = "contrib"
+name = "Contributor-facing changes"
 showcontent = true
 
 [[tool.towncrier.type]]
-directory = "trivial"
-name = "Trivial/Internal Changes"
+# Changes that are hard to assign to any of the above categories.
+directory = "misc"
+name = "Miscellaneous internal changes"
 showcontent = true
 
 [tool.mypy]