Add title_format tests and drop a line

README.rst

@@ -146,6 +146,10 @@ Towncrier has the following global options, which can be specified in the toml f
 
 If a single file is used, the content of that file gets overwritten each time.
 
+If ``title_format`` is unspecified or an empty string, the default format will be used.
+If set to ``false``, no title will be created.
+This can be useful if the specified template creates the title itself.
+
 Furthermore, you can add your own fragment types using:
 
 .. code-block:: ini

src/towncrier/test/test_build.py

@@ -671,3 +671,111 @@ def test_bullet_points_false(self):
             """
             ).lstrip(),
         )
+
+    def test_title_format_custom(self):
+        """
+        A non-empty title format adds the specified title.
+        """
+        runner = CliRunner()
+
+        with runner.isolated_filesystem():
+            with open("pyproject.toml", "w") as f:
+                f.write(dedent("""\
+                    [tool.towncrier]
+                    package = "foo"
+                    title_format = "[{project_date}] CUSTOM RELEASE for {name} version {version}"
+                """))
+            os.mkdir("foo")
+            os.mkdir("foo/newsfragments")
+            with open("foo/newsfragments/123.feature", "w") as f:
+                f.write("Adds levitation")
+            # Towncrier ignores .rst extension
+            with open("foo/newsfragments/124.feature.rst", "w") as f:
+                f.write("Extends levitation")
+
+            result = runner.invoke(
+                _main,
+                [
+                    "--name",
+                    "FooBarBaz",
+                    "--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.
+
+            [20-01-2001] CUSTOM RELEASE for FooBarBaz version 7.8.9
+            =======================================================
+
+            Features
+            --------
+
+            - Adds levitation (#123)
+            - Extends levitation (#124)
+
+        """)
+
+        self.assertEqual(0, result.exit_code)
+        self.assertEqual(expected_output, result.output)
+
+    def test_title_format_false(self):
+        """
+        Setting the title format to false disables the explicit title.  This
+        would be used, for example, when the template creates the title itself.
+        """
+        runner = CliRunner()
+
+        with runner.isolated_filesystem():
+            with open("pyproject.toml", "w") as f:
+                f.write(dedent("""\
+                    [tool.towncrier]
+                    package = "foo"
+                    title_format = false
+                """))
+            os.mkdir("foo")
+            os.mkdir("foo/newsfragments")
+            # Towncrier ignores .rst extension
+            with open("foo/newsfragments/124.feature.rst", "w") as f:
+                f.write("Extends levitation")
+
+            result = runner.invoke(
+                _main,
+                [
+                    "--name",
+                    "FooBarBaz",
+                    "--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.
+
+            FooBarBaz 7.8.9 (20-01-2001)
+            ============================
+
+            Features
+            --------
+
+            - Extends levitation (#124)
+
+        """)
+
+        self.assertEqual(0, result.exit_code)
+        self.assertEqual(expected_output, result.output)