Improve our towncrier template, to do the right thing after releases

docs/html/news.rst

@@ -7,6 +7,6 @@ Changelog
     Major and minor releases of pip also include changes listed within
     prior beta releases.
 
-.. towncrier-draft-entries:: |release|, unreleased as on
+.. towncrier-draft-entries:: Not yet released
 
 .. pip-news-include:: ../../NEWS.rst

pyproject.toml

@@ -3,13 +3,19 @@ requires = ["setuptools", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [tool.towncrier]
+# For finding the __version__
 package = "pip"
 package_dir = "src"
+# For writing into the correct file
 filename = "NEWS.rst"
+# For finding the news fragments
 directory = "news/"
-title_format = "{version} ({project_date})"
+
+# For rendering properly for this project
 issue_format = "`#{issue} <https://github.com/pypa/pip/issues/{issue}>`_"
 template = "tools/news/template.rst"
+
+# Grouping of entries, within our changelog
 type = [
   { name = "Process",                   directory = "process", showcontent = true },
   { name = "Deprecations and Removals", directory = "removal", showcontent = true },

tools/news/template.rst

@@ -1,41 +1,46 @@
-{% set underline = "=" %}
+{# This is a heavily customised version of towncrier's default template. #}
 
-{{ underline * ((top_line)|length) }}
-{% for section in sections %}
-{% set underline = "-" %}
-{% if section %}
-{{ section }}
-{{ underline * section|length }}{% set underline = "~" %}
+{#-
+  Only render if there's any changes to show.
 
-{% endif %}
-{% if sections[section] %}
-{% for category, val in definitions.items() if category in sections[section] and category != 'trivial' %}
+  This serves as a compatibility "hack" since we render unreleased news entries
+  in our changelog with ``sphinxcontrib.towncrier``; which triggers a render even
+  when there's no entries to be rendered.
+#}
+{% if sections[''] %}
 
-{{ definitions[category]['name'] }}
-{{ underline * definitions[category]['name']|length }}
+{#- Heading for individual version #}
+{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 3) }}
 
-{% if definitions[category]['showcontent'] %}
-{% for text, values in sections[section][category]|dictsort(by='value') %}
-- {{ text }}{% if category != 'vendor' and category != 'process' %} ({{ values|sort|join(', ') }}){% endif %}
+{#
 
-{% endfor %}
-{% else %}
-- {{ sections[section][category]['']|sort|join(', ') }}
+  The following loop will run exactly once, with ``section_name == ""``.
 
+  This is due to the undocumented "sections" feature in towncrier.
+  See https://github.com/twisted/towncrier/issues/61.
 
-{% endif %}
-{% if sections[section][category]|length == 0 %}
+  We don't use this feature, and this template doesn't render the section
+  heading for that reason.
+#}
+{% for section_name, entries_by_type in sections.items() -%}
+{# Only show types with entries and ``showcontent = true``, using the order from pyproject.toml #}
+{% for type_ in definitions if (sections[section_name][type_] and definitions[type_]['showcontent']) %}
 
-No significant changes.
+{# Heading for individual types #}
+{{ definitions[type_]['name'] }}
+{{ underlines[0] * definitions[type_]['name']|length }}
 
-
-{% else %}
-{% endif %}
+{# This is the loop that generates individual entries #}
+{% for message, issue_reference in sections[section_name][type_]|dictsort(by='value') %}
+- {{ message }}
+  {%- if type_ not in ["vendor", "process"] %} ({{ issue_reference|sort|join(', ') }}){% endif %}
 {% endfor %}
-{% else %}
 
+{% else %}
+{# We only have entries where the type has ``showcontent = true``. #}
 No significant changes.
 
-
-{% endif %}
-{% endfor %}
+{% endfor -%}
+{% endfor -%}
+{% endif -%}