Orphans in non showcontent categories (#612)

* Always content for orphans, since they don't have a concept of tickets

* Add tests for orphans in non showcontent categories

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add newsfragment

* Add a note in the configuration docs about the change to orphan fragments in non-showcontent categories

* Use rst admonitions for the showcontent notes

* Refactor rendering of title via `config.title_format` (#610)

* Refactor rendering of title via config.title_format

* Add newsfragment

* Config docs

* Fix restructuredtext formatting error

* Refactor issue_key function to sort issues in a human-friendly way (#608)

* Refactor issue_key function to sort issues in a human-friendly way

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Rename newsfragment

* Small improvement to test to show how text with numeric issues are sorted

* Update src/towncrier/_builder.py docstring grammar

Co-authored-by: Adi Roiban <[email protected]>

* clarify new behaviour in newsfragment

* Add some docstrings/comments to tests

* linelength fix

* Clarify news fragments vs tickets

Co-authored-by: Adi Roiban <[email protected]>

* Consistent use of "issue" rather than "ticket"

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* typo

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Adi Roiban <[email protected]>

* variable now called issue instead of ticket

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Adi Roiban <[email protected]>

Author: 3 people

docs/configuration.rst

@@ -216,6 +216,11 @@ These may include the following optional keys:
 
     ``true`` by default.
 
+    .. note::
+
+        Orphan fragments (those without an issue number) always have their content included.
+        If a fragment was created, it means that information is important for end users.
+
 For example, if you want your custom fragment types to be ``["feat", "fix", "chore",]`` and you want all of them to use the default configuration except ``"chore"`` you can do it as follows:
 
 .. code-block:: toml
@@ -257,6 +262,11 @@ Each table within this array has the following mandatory keys:
 
     ``true`` by default.
 
+    .. note::
+
+        Orphan fragments (those without an issue number) always have their content included.
+        If a fragment was created, it means that information is important for end users.
+
 For example:
 
 .. code-block:: toml

src/towncrier/_builder.py

@@ -191,7 +191,11 @@ def split_fragments(
                 # Assume the text is formatted correctly
                 content = content.rstrip()
 
-            if definitions[category]["showcontent"] is False:
+            if definitions[category]["showcontent"] is False and issue:
+                # If this category is not supposed to show content (and we have an
+                # issue) then we should just add the issue to the section rather than
+                # the content. If there isn't an issue, still add the content so that
+                # it's recorded.
                 content = ""
 
             texts = section.setdefault(category, {})

src/towncrier/newsfragments/612.bugfix.rst

@@ -0,0 +1 @@
+Orphan news fragments, fragments not associated with an issue, will now still show in categories that are marked to not show content, since they do not have an issue number to show.

src/towncrier/templates/default.md

@@ -15,7 +15,6 @@
 {% for category, val in definitions.items() if category in sections[section] %}
 ### {{ definitions[category]['name'] }}
 
-{% if definitions[category]['showcontent'] %}
 {% for text, values in sections[section][category].items() %}
 - {{ text }}
 {%- if values %}
@@ -24,24 +23,18 @@
 
   (
 {%- else %}
- (
+{% if text %} ({% endif %}
 {%- endif -%}
 {%- for issue in values %}
 {{ issue.split(": ", 1)[0] }}{% if not loop.last %}, {% endif %}
 {%- endfor %}
-)
+{% if text %}){% endif %}
+
 {% else %}
 
 {% endif %}
 {% endfor %}
 
-{% else %}
-- {% for issue in sections[section][category][''] %}
-{{ issue.split(": ", 1)[0] }}{% if not loop.last %}, {% endif %}
-{% endfor %}
-
-
-{% endif %}
 {% if issues_by_category[section][category] and "]: " in issues_by_category[section][category][0] %}
 {% for issue in issues_by_category[section][category] %}
 {{ issue }}

src/towncrier/templates/default.rst

@@ -18,16 +18,11 @@
 {{ definitions[category]['name'] }}
 {{ underline * definitions[category]['name']|length }}
 
-{% if definitions[category]['showcontent'] %}
 {% for text, values in sections[section][category].items() %}
-- {{ text }}{% if values %} ({{ values|join(', ') }}){% endif %}
+- {% if text %}{{ text }}{% if values %} ({{ values|join(', ') }}){% endif %}{% else %}{{ values|join(', ') }}{% endif  %}
 
 {% endfor %}
 
-{% else %}
-- {{ sections[section][category]['']|join(', ') }}
-
-{% endif %}
 {% if sections[section][category]|length == 0 %}
 No significant changes.
 

src/towncrier/test/test_build.py

@@ -1416,6 +1416,115 @@ def test_with_topline_and_template_and_draft(self, runner):
             - Adds levitation
 
 
+        """
+        )
+
+        self.assertEqual(0, result.exit_code, result.output)
+        self.assertEqual(expected_output, result.output)
+
+    @with_project(
+        config="""
+        [tool.towncrier]
+        """
+    )
+    def test_orphans_in_non_showcontent(self, runner):
+        """
+        When ``showcontent`` is false (like in the ``misc`` category by default),
+        orphans are still rendered because they don't have an issue number to display.
+        """
+        os.mkdir("newsfragments")
+        with open("newsfragments/123.misc", "w") as f:
+            f.write("Misc")
+        with open("newsfragments/345.misc", "w") as f:
+            f.write("Another misc")
+        with open("newsfragments/+.misc", "w") as f:
+            f.write("Orphan misc still displayed!")
+        with open("newsfragments/+2.misc", "w") as f:
+            f.write("Another orphan misc still displayed!")
+
+        result = runner.invoke(
+            _main,
+            [
+                "--version=7.8.9",
+                "--date=20-01-2001",
+                "--draft",
+            ],
+        )
+
+        expected_output = dedent(
+            """\
+            Loading template...
+            Finding news fragments...
+            Rendering news fragments...
+            Draft only -- nothing has been written.
+            What is seen below is what would be written.
+
+            7.8.9 (20-01-2001)
+            ==================
+
+            Misc
+            ----
+
+            - #123, #345
+            - Another orphan misc still displayed!
+            - Orphan misc still displayed!
+
+
+
+        """
+        )
+
+        self.assertEqual(0, result.exit_code, result.output)
+        self.assertEqual(expected_output, result.output)
+
+    @with_project(
+        config="""
+        [tool.towncrier]
+        filename = "CHANGES.md"
+        """
+    )
+    def test_orphans_in_non_showcontent_markdown(self, runner):
+        """
+        When ``showcontent`` is false (like in the ``misc`` category by default),
+        orphans are still rendered because they don't have an issue number to display.
+        """
+        os.mkdir("newsfragments")
+        with open("newsfragments/123.misc", "w") as f:
+            f.write("Misc")
+        with open("newsfragments/345.misc", "w") as f:
+            f.write("Another misc")
+        with open("newsfragments/+.misc", "w") as f:
+            f.write("Orphan misc still displayed!")
+        with open("newsfragments/+2.misc", "w") as f:
+            f.write("Another orphan misc still displayed!")
+
+        result = runner.invoke(
+            _main,
+            [
+                "--version=7.8.9",
+                "--date=20-01-2001",
+                "--draft",
+            ],
+        )
+
+        expected_output = dedent(
+            """\
+            Loading template...
+            Finding news fragments...
+            Rendering news fragments...
+            Draft only -- nothing has been written.
+            What is seen below is what would be written.
+
+            # 7.8.9 (20-01-2001)
+
+            ### Misc
+
+            - #123, #345
+            - Another orphan misc still displayed!
+            - Orphan misc still displayed!
+
+
+
         """
         )