Merge pull request #1593 from njsmith/better-newsfragment-categories

Minor overhaul of our newsfragment categories

Author: oremanj

newsfragments/1574.removal.rst renamed to newsfragments/1574.deprecated.rst

@@ -8,20 +8,28 @@ relevant to people working on the code itself.)
 Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
 ``<ISSUE>`` is an issue numbers, and ``<TYPE>`` is one of:
 
-* ``feature``
+* ``headline``: a major new feature we want to highlight for users
+* ``breaking``: any breaking changes that happen without a proper
+  deprecation period (note: deprecations, and removal of previously
+  deprecated features after an appropriate time, go in the
+  ``deprecated`` category instead)
+* ``feature``: any new feature that doesn't qualify for ``headline``
 * ``bugfix``
 * ``doc``
-* ``removal``
+* ``deprecated``
 * ``misc``
 
-So for example: ``123.feature.rst``, ``456.bugfix.rst``
+So for example: ``123.headline.rst``, ``456.bugfix.rst``,
+``789.deprecated.rst``
 
 If your PR fixes an issue, use that number here. If there is no issue,
 then after you submit the PR and get the PR number you can add a
 newsfragment using that instead.
 
-Note that the ``towncrier`` tool will automatically
-reflow your text, so don't try to do any fancy formatting. You can
-install ``towncrier`` and then run ``towncrier --draft`` if you want
-to get a preview of how your change will look in the final release
-notes.
+Your text can use all the same markup that we use in our Sphinx docs.
+For example, you can use double-backticks to mark code snippets, or
+single-backticks to link to a function/class/module.
+
+To check how your formatting looks, the easiest way is to make the PR,
+and then after the CI checks run, click on the "Read the Docs build"
+details link, and navigate to the release history page.

newsfragments/399.feature.rst renamed to newsfragments/399.headline.rst

@@ -15,8 +15,15 @@ directory = "newsfragments"
 underlines = ["-", "~", "^"]
 issue_format = "`#{issue} <https://github.com/python-trio/trio/issues/{issue}>`__"
 
-# Unfortunately there's no way to simply override
-# tool.towncrier.type.misc.showcontent
+[[tool.towncrier.type]]
+directory = "headline"
+name = "Headline features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking changes"
+showcontent = true
 
 [[tool.towncrier.type]]
 directory = "feature"
@@ -30,12 +37,12 @@ showcontent = true
 
 [[tool.towncrier.type]]
 directory = "doc"
-name = "Improved Documentation"
+name = "Improved documentation"
 showcontent = true
 
 [[tool.towncrier.type]]
-directory = "removal"
-name = "Deprecations and Removals"
+directory = "deprecated"
+name = "Deprecations and removals"
 showcontent = true
 
 [[tool.towncrier.type]]