fix(changelog): clearer error when changelog format cannot be inferred

When `changelog_format` was unset and the changelog filename had an
unknown extension (e.g. `CHANGELOG.md.sections`), commitizen raised
`Unknown changelog format 'None'` -- which is confusing because the
user never set anything to `None`.

Improve the two failure paths:

* If the user set `changelog_format` to an unknown value, the error
  echoes that value and lists the registered formats.
* If the format had to be inferred from the filename and the inference
  failed, the error names the offending filename, points to the
  `changelog_format` setting and lists the registered formats.

No behaviour change for the success paths.

Closes #894

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bearomorphism

commitizen/changelog_formats/__init__.py

@@ -67,15 +67,26 @@ def get_changelog_format(
     """
     Get a format from its name
 
-    :raises FormatUnknown: if a non-empty name is provided but cannot be found in the known formats
+    :raises ChangelogFormatUnknown: if a non-empty name is provided but cannot
+        be found in the known formats, or if the filename's extension cannot
+        be matched to a known format and no ``changelog_format`` is set.
     """
     name: str | None = config.settings.get("changelog_format")
     format = (
         name and KNOWN_CHANGELOG_FORMATS.get(name) or _guess_changelog_format(filename)
     )
 
     if not format:
-        raise ChangelogFormatUnknown(f"Unknown changelog format '{name}'")
+        known = ", ".join(sorted(KNOWN_CHANGELOG_FORMATS)) or "(none registered)"
+        if name:
+            raise ChangelogFormatUnknown(
+                f"Unknown changelog format '{name}'. Known formats: {known}."
+            )
+        raise ChangelogFormatUnknown(
+            "Cannot infer changelog format from filename "
+            f"'{filename}'. Set the `changelog_format` setting "
+            f"explicitly. Known formats: {known}."
+        )
 
     return format(config)
 

tests/test_changelog_formats.py

@@ -53,11 +53,33 @@ def test_get_format_empty_filename(config: BaseConfig, filename: str | None):
 @pytest.mark.parametrize("filename", [None, ""])
 def test_get_format_empty_filename_no_setting(config: BaseConfig, filename: str | None):
     config.settings["changelog_format"] = None
-    with pytest.raises(ChangelogFormatUnknown):
+    with pytest.raises(ChangelogFormatUnknown) as excinfo:
         get_changelog_format(config, filename)
+    # The error message should hint at setting `changelog_format` and list
+    # the known formats so users on non-standard file extensions know what
+    # to do (#894).
+    msg = str(excinfo.value)
+    assert "changelog_format" in msg
+    assert "Known formats" in msg
 
 
 @pytest.mark.parametrize("filename", ["extensionless", "file.unknown"])
 def test_get_format_unknown(config: BaseConfig, filename: str | None):
-    with pytest.raises(ChangelogFormatUnknown):
+    with pytest.raises(ChangelogFormatUnknown) as excinfo:
         get_changelog_format(config, filename)
+    # Same hint when the filename extension is unknown.
+    msg = str(excinfo.value)
+    assert "changelog_format" in msg
+    assert "Known formats" in msg
+
+
+def test_get_format_unknown_name_lists_known_formats(config: BaseConfig):
+    """Regression test for #894: when ``changelog_format`` is set to an
+    unknown value, the error must list the registered formats so users
+    can self-correct."""
+    config.settings["changelog_format"] = "definitely-not-a-format"
+    with pytest.raises(ChangelogFormatUnknown) as excinfo:
+        get_changelog_format(config)
+    msg = str(excinfo.value)
+    assert "definitely-not-a-format" in msg
+    assert "Known formats" in msg