📝 Add comments to change note categories

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