💅 Introduce more accurate changelog categories

Specifically, the new Towncrier fragment types are set up to be
`bugfix`, `feature`, `deprecation`, `breaking`, `doc`, `packaging`,
`contrib`, `misc`.

Previously, the `misc` fragments were rendered without the entry
context, just as a list of PR numbers. With this change, the change
note text is displayed as usual.

Author: webknjaz

.github/PULL_REQUEST_TEMPLATE.md

@@ -21,13 +21,35 @@
 - [ ] If you provide code modification, please add yourself to `CONTRIBUTORS.txt`
   * The format is <Name> <Surname>.
   * Please keep alphabetical order, the file is sorted by names.
-- [ ] Add a new news fragment into the `CHANGES` folder
-  * name it `<issue_id>.<type>` for example (588.bugfix)
-  * if you don't have an `issue_id` change it to the pr id after creating the pr
-  * ensure type is one of the following:
-    * `.feature`: Signifying a new feature.
-    * `.bugfix`: Signifying a bug fix.
-    * `.doc`: Signifying a documentation improvement.
-    * `.removal`: Signifying a deprecation or removal of public API.
-    * `.misc`: A ticket has been closed, but it is not of interest to users.
-  * Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files."
+- [ ] Add a new news fragment into the `CHANGES/` folder
+  * name it `<issue_or_pr_num>.<type>.rst` (e.g. `588.bugfix.rst`)
+  * if you don't have an issue number, change it to the pull request
+    number after creating the PR
+    * `.bugfix`: A bug fix for something the maintainers deemed an
+      improper undesired behavior that got corrected 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 is 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.
+  * Make sure to use full sentences with correct case and punctuation,
+    for example:
+    ```rst
+    Fixed issue with non-ascii contents in doctest text files
+    -- by :user:`contributor-gh-handle`.
+    ```
+
+    Use the past tense or the present tense a non-imperative mood,
+    referring to what's changed compared to the last released version
+    of this project.

.pre-commit-config.yaml

@@ -6,7 +6,16 @@ repos:
     language: fail
     entry: >-
       Changelog files must be named
-      ####.(bugfix|feature|removal|doc|misc)(.#)?(.rst)?
+      ####.(
+      bugfix
+      | feature
+      | deprecation
+      | breaking
+      | doc
+      | packaging
+      | contrib
+      | misc
+      )(.#)?(.rst)?
     exclude: >-
       (?x)
       ^
@@ -15,8 +24,11 @@ repos:
           |(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40})\.(
             bugfix
             |feature
-            |removal
+            |deprecation
+            |breaking
             |doc
+            |packaging
+            |contrib
             |misc
           )(\.\d+)?(\.rst)?
           |README\.rst

CHANGES/.gitignore

@@ -1 +1,28 @@
+*
+!.TEMPLATE.rst
 !.gitignore
+!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
+!*.misc
+!*.misc.rst
+!*.misc.*.rst
+!*.packaging
+!*.packaging.rst
+!*.packaging.*.rst

CHANGES/2835.removal renamed to CHANGES/2835.breaking.rst

@@ -43,19 +43,32 @@ with 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``, ``misc`` 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:
 
-- ``feature``: Any new feature
-- ``bugfix``: A bug fix
-- ``doc``: A change to the documentation
-- ``misc``: Changes internal to the repo like CI, test and build changes
-- ``removal``: For deprecations and removals of an existing feature or behavior
+- ``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

CHANGES/2977.removal renamed to CHANGES/2977.breaking.rst

@@ -12,6 +12,67 @@ build-backend = "setuptools.build_meta"
   template = "CHANGES/.TEMPLATE.rst"
   issue_format = "{issue}"
 
+  # 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 = ""
+
+  [[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]]
+    # New behaviors, public APIs. That sort of stuff.
+    directory = "feature"
+    name = "Features"
+    showcontent = true
+
+  [[tool.towncrier.type]]
+    # Declarations of future API removals and breaking changes in behavior.
+    directory = "deprecation"
+    name = "Deprecations (removal in next major release)"
+    showcontent = true
+
+  [[tool.towncrier.type]]
+    # When something public gets removed in a breaking way. Could be
+    # deprecated in an earlier release.
+    directory = "breaking"
+    name = "Removals and backward incompatible breaking changes"
+    showcontent = true
+
+  [[tool.towncrier.type]]
+    # Notable updates to the documentation structure or build process.
+    directory = "doc"
+    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"
+    name = "Miscellaneous internal changes"
+    showcontent = true
+
 
 [tool.cibuildwheel]
 test-command = ""

CHANGES/3463.removal renamed to CHANGES/3463.breaking.rst

@@ -4,8 +4,21 @@
 import sys
 from pathlib import Path
 
-ALLOWED_SUFFIXES = ["feature", "bugfix", "doc", "removal", "misc"]
-PATTERN = re.compile(r"\d+\.(" + "|".join(ALLOWED_SUFFIXES) + r")(\.\d+)?(\.rst)?")
+ALLOWED_SUFFIXES = (
+    "bugfix",
+    "feature",
+    "deprecation",
+    "breaking",
+    "doc",
+    "packaging",
+    "contrib",
+    "misc",
+)
+PATTERN = re.compile(
+    r"(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40})\.("
+    + "|".join(ALLOWED_SUFFIXES)
+    + r")(\.\d+)?(\.rst)?",
+)
 
 
 def get_root(script_path):

CHANGES/3538.removal renamed to CHANGES/3538.breaking.rst

@@ -7,8 +7,21 @@
 import subprocess
 from pathlib import Path
 
-ALLOWED_SUFFIXES = ["feature", "bugfix", "doc", "removal", "misc"]
-PATTERN = re.compile(r"(\d+)\.(" + "|".join(ALLOWED_SUFFIXES) + r")(\.\d+)?(\.rst)?")
+ALLOWED_SUFFIXES = (
+    "bugfix",
+    "feature",
+    "deprecation",
+    "breaking",
+    "doc",
+    "packaging",
+    "contrib",
+    "misc",
+)
+PATTERN = re.compile(
+    r"(\d+|[0-9a-f]{8}|[0-9a-f]{7}|[0-9a-f]{40})\.("
+    + "|".join(ALLOWED_SUFFIXES)
+    + r")(\.\d+)?(\.rst)?",
+)
 
 
 def main():
@@ -18,9 +31,10 @@ def main():
     for fname in (root / "CHANGES").iterdir():
         match = PATTERN.match(fname.name)
         if match is not None:
-            num = match.group(1)
-            tst = f"`#{num} <https://github.com/aio-libs/aiohttp/issues/{num}>`_"
-            if tst in changes:
+            commit_issue_or_pr = match.group(1)
+            tst_issue_or_pr = f":issue:`{commit_issue_or_pr}`"
+            tst_commit = f":commit:`{commit_issue_or_pr}`"
+            if tst_issue_or_pr in changes or tst_commit in changes:
                 subprocess.run(["git", "rm", fname])
                 delete.append(fname.name)
     print("Deleted CHANGES records:", " ".join(delete))