From 5c208cc206276c91c73ac2e71f15da54cefe9f75 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Tue, 28 Nov 2023 22:48:22 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20`contrib`=20&=20`packaging?=
 =?UTF-8?q?`=20change=20note=20types?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/changelog-fragments/.gitignore      |  6 +++++
 docs/changelog-fragments/539.contrib.rst |  0
 docs/changelog-fragments/README.rst      | 30 +++++++++++++++++++++++-
 pyproject.toml                           | 14 +++++++++++
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 docs/changelog-fragments/539.contrib.rst

diff --git a/docs/changelog-fragments/.gitignore b/docs/changelog-fragments/.gitignore
index 8953f66dc..3b11fef60 100644
--- a/docs/changelog-fragments/.gitignore
+++ b/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
diff --git a/docs/changelog-fragments/539.contrib.rst b/docs/changelog-fragments/539.contrib.rst
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/changelog-fragments/README.rst b/docs/changelog-fragments/README.rst
index c4108b04c..c60f4c958 100644
--- a/docs/changelog-fragments/README.rst
+++ b/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
 -----------------------------------------------------------
diff --git a/pyproject.toml b/pyproject.toml
index cd0de3f22..1b8d05ef4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -113,6 +113,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"