From 0cf92cfa4cd4a0c156dbf3dc0e83b7274996a03b Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Thu, 20 Jun 2024 18:30:08 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20comments=20to=20change=20n?=
 =?UTF-8?q?ote=20categories?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pyproject.toml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/pyproject.toml b/pyproject.toml
index 734c508ca..895cedb5f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -372,42 +372,58 @@ 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"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Declarations of future API removals and breaking changes in behavior.
 directory = "deprecation"
 name = "Deprecations"
 showcontent = true
 
 [[tool.towncrier.type]]
+# New behaviors, public APIs. That sort of stuff.
 directory = "feature"
 name = "Features"
 showcontent = true
 
 [[tool.towncrier.type]]
+# New behaviors in existing features.
 directory = "improvement"
 name = "Improvements"
 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"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Updates regarding bundling dependencies.
 directory = "vendor"
 name = "Vendored Libraries"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Notable updates to the documentation structure or build process.
 directory = "doc"
 name = "Improved Documentation"
 showcontent = true
 
 [[tool.towncrier.type]]
+# Changes that might not even be worth exposing to the end users.
 directory = "trivial"
 name = "Trivial/Internal Changes"
 showcontent = true