📝 Add contrib & packaging change note types

.pre-commit-config.yaml

@@ -148,7 +148,16 @@ repos:
     language: fail
     entry: >-
       Changelog files must be named
-      ####.(bugfix|feature|deprecation|breaking|doc|misc)(.#)?(.rst)?
+      ####.(
+      bugfix
+      | feature
+      | deprecation
+      | breaking
+      | doc
+      | packaging
+      | contrib
+      | misc
+      )(.#)?(.rst)?
     exclude: >-
       (?x)
       ^
@@ -160,6 +169,8 @@ repos:
             |deprecation
             |breaking
             |doc
+            |packaging
+            |contrib
             |misc
           )(\.\d+)?(\.rst)?
           |README\.rst

docs/changelog-fragments/.gitignore

@@ -8,6 +8,9 @@
 !*.breaking
 !*.breaking.rst
 !*.breaking.*.rst
+!*.contrib
+!*.contrib.rst
+!*.contrib.*.rst
 !*.deprecation
 !*.deprecation.rst
 !*.deprecation.*.rst
@@ -20,3 +23,6 @@
 !*.misc
 !*.misc.rst
 !*.misc.*.rst
+!*.packaging
+!*.packaging.rst
+!*.packaging.*.rst

docs/changelog-fragments/539.contrib.rst

@@ -0,0 +1,6 @@
+Added separate changelog fragment types for contributor-
+and downstream-facing patches -- by :user:`webknjaz`.
+
+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.

docs/changelog-fragments/README.rst

@@ -41,11 +41,39 @@ your own!).
 Finally, name your file following the convention that Towncrier
 understands: it should start with the number of an issue or a
 PR followed by a dot, then add a patch type, like ``feature``,
-``doc``, ``bugfix`` etc., and add ``.rst`` as a suffix. If you
+``doc``, ``contrib`` etc., and add ``.rst`` as a suffix. If you
 need to add more than one fragment, you may add an optional
 sequence number (delimited with another period) between the type
 and the suffix.
 
+In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+where the categories are:
+
+- ``bugfix``: A bug fix for something we deemed an improper undesired
+  behavior that got corrected in the release to match pre-agreed
+  expectations.
+- ``feature``: A new behavior, public APIs. That sort of stuff.
+- ``deprecation``: A declaration of future API removals and breaking
+  changes in behavior.
+- ``breaking``: When something public gets removed in a breaking way.
+  Could be deprecated in an earlier release.
+- ``doc``: Notable updates to the documentation structure or build
+  process.
+- ``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.
+
+A pull request may have more than one of these components, for example
+a code change may introduce a new feature that deprecates an old
+feature, in which case two fragments should be added. It is not
+necessary to make a separate documentation fragment for documentation
+changes accompanying the relevant code changes.
+
 -----------------------------------------------------------
 Examples for changelog entries adding to your Pull Requests
 -----------------------------------------------------------

pyproject.toml

@@ -78,6 +78,12 @@ profile = "True"
   title_format = "v{version} ({project_date})"
   underlines = ["=", "^", "-", "~"]
 
+  # 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.section]]
     path = ""
 
@@ -113,6 +119,20 @@ profile = "True"
     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]]
     # Changes that are hard to assign to any of the above categories.
     directory = "misc"