feat: add changelog_skip_prereleases setting to omit prerelease entries

When changelog_skip_prereleases = true is set, prerelease tags (rc,
alpha, beta, dev) are omitted entirely from the generated changelog.
Both cz changelog and cz bump --changelog honour the setting.

When both changelog_skip_prereleases and changelog_merge_prerelease
are set, skip takes precedence and prerelease entries are dropped.

Closes #1218

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

Author: bearomorphism

commitizen/commands/changelog.py

@@ -55,20 +55,32 @@ def __init__(self, config: BaseConfig, arguments: ChangelogArgs) -> None:
 
         self.config = config
 
-        changelog_file_name = arguments.get("file_name") or self.config.settings.get(
-            "changelog_file"
-        )
+        # Distinguish the source of the file name so we can apply the correct
+        # path resolution strategy:
+        #   • CLI-provided (--file-name): use as-is, relative to the current
+        #     working directory — standard CLI convention.
+        #   • Config-provided (changelog_file setting): resolve relative to the
+        #     config file's directory so the path is stable regardless of where
+        #     the user runs `cz` from.
+        file_name_from_args: str | None = arguments.get("file_name") or None
+        file_name_from_config: str | None = self.config.settings.get("changelog_file")
+        changelog_file_name = file_name_from_args or file_name_from_config
         if not isinstance(changelog_file_name, str):
             raise NotAllowed(
                 "Changelog file name is broken.\n"
                 "Check the flag `--file-name` in the terminal "
                 f"or the setting `changelog_file` in {self.config.path}"
             )
-        self.file_name = (
-            Path(self.config.path.parent, changelog_file_name).as_posix()
-            if self.config.path is not None
-            else changelog_file_name
-        )
+        if file_name_from_args:
+            # Explicit CLI argument — keep relative to cwd (or use as-is if absolute).
+            self.file_name = file_name_from_args
+        elif self.config.path is not None:
+            # From configuration — anchor to the config file's directory.
+            self.file_name = Path(
+                self.config.path.parent, changelog_file_name
+            ).as_posix()
+        else:
+            self.file_name = changelog_file_name
 
         self.cz = factory.committer_factory(self.config)
 
@@ -114,6 +126,9 @@ def __init__(self, config: BaseConfig, arguments: ChangelogArgs) -> None:
             ignored_tag_formats=self.config.settings["ignored_tag_formats"],
             merge_prereleases=arguments.get("merge_prerelease")
             or self.config.settings["changelog_merge_prerelease"],
+            skip_prereleases=bool(
+                self.config.settings.get("changelog_skip_prereleases")
+            ),
         )
 
         self.template = (

commitizen/defaults.py

@@ -40,6 +40,7 @@ class Settings(TypedDict, total=False):
     changelog_format: str | None
     changelog_incremental: bool
     changelog_merge_prerelease: bool
+    changelog_skip_prereleases: bool
     changelog_start_rev: str | None
     customize: CzSettings
     encoding: str
@@ -103,6 +104,7 @@ class Settings(TypedDict, total=False):
     "changelog_incremental": False,
     "changelog_start_rev": None,
     "changelog_merge_prerelease": False,
+    "changelog_skip_prereleases": False,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,

commitizen/tags.py

@@ -86,6 +86,7 @@ class TagRules:
     legacy_tag_formats: Sequence[str] = field(default_factory=list)
     ignored_tag_formats: Sequence[str] = field(default_factory=list)
     merge_prereleases: bool = False
+    skip_prereleases: bool = False
 
     @property
     def tag_formats(self) -> Iterable[str]:
@@ -166,7 +167,13 @@ def include_in_changelog(self, tag: GitTag) -> bool:
             version = self.extract_version(tag)
         except InvalidVersion:
             return False
-        return not (self.merge_prereleases and version.is_prerelease)
+        if version.is_prerelease:
+            # skip_prereleases wins over merge_prereleases when both are set
+            if self.skip_prereleases:
+                return False
+            if self.merge_prereleases:
+                return False
+        return True
 
     def search_version(self, text: str, last: bool = False) -> VersionTag | None:
         """
@@ -265,6 +272,7 @@ def from_settings(cls, settings: Settings) -> Self:
             legacy_tag_formats=settings["legacy_tag_formats"],
             ignored_tag_formats=settings["ignored_tag_formats"],
             merge_prereleases=settings["changelog_merge_prerelease"],
+            skip_prereleases=settings["changelog_skip_prereleases"],
         )
 
     def _extract_version(self, match: re.Match[str]) -> str:

docs/commands/changelog.md

@@ -85,6 +85,8 @@ Specify the name of the output file. Note that changelog generation only works w
 cz changelog --file-name="CHANGES.md"
 ```
 
+When provided on the command line, the path is interpreted **relative to the current working directory** (standard CLI convention).
+
 This value can be updated in the configuration file with the key `changelog_file` under `tool.commitizen`.
 
 ```toml
@@ -93,6 +95,8 @@ This value can be updated in the configuration file with the key `changelog_file
 changelog_file = "CHANGES.md"
 ```
 
+When set in the configuration file, the path is resolved **relative to the configuration file's directory** (usually the project root).  This means the location of the changelog is stable regardless of which directory you run `cz` from.
+
 ### `--incremental`
 
 Build from the latest version found in changelog.
@@ -147,6 +151,30 @@ This flag can be set in the configuration file with the key `changelog_merge_pre
 changelog_merge_prerelease = true
 ```
 
+### `changelog_skip_prereleases`
+
+Omits all prerelease versions (e.g. `rc`, `alpha`, `beta`, `dev`) from the changelog entirely. Stable-release entries are kept, but their commits are attributed only to the stable release — prerelease headers never appear.
+
+This is a configuration-only option (no CLI flag); enable it in your `pyproject.toml`:
+
+```toml
+[tool.commitizen]
+changelog_skip_prereleases = true
+```
+
+With this setting, a history such as:
+
+```
+0.1.0-a0  →  0.1.0-b0  →  0.1.0
+```
+
+will produce a changelog that shows only `0.1.0`, without `0.1.0-a0` or `0.1.0-b0` entries.
+
+!!! note
+    When both `changelog_skip_prereleases = true` and `changelog_merge_prerelease = true` are set,
+    `changelog_skip_prereleases` takes precedence and prerelease entries are dropped rather than
+    merged.
+
 ### `--template`
 
 Provide your own changelog Jinja template by using the `template` settings or the `--template` parameter.

tests/commands/test_changelog_command.py

@@ -599,6 +599,79 @@ def test_changelog_config_flag_merge_prerelease(
     file_regression.check(out, extension=".md")
 
 
+@pytest.mark.usefixtures("tmp_commitizen_project")
+def test_changelog_config_flag_skip_prereleases(
+    capsys: pytest.CaptureFixture,
+    config_path: Path,
+    util: UtilFixture,
+):
+    """changelog_skip_prereleases = true must omit prerelease entries from changelog."""
+    with config_path.open("a", encoding="utf-8") as f:
+        f.write("changelog_skip_prereleases = true\n")
+
+    util.create_file_and_commit("feat: initial feature")
+    util.run_cli("bump", "--yes")
+    capsys.readouterr()
+
+    util.create_file_and_commit("feat: add new output")
+    util.create_file_and_commit("fix: output glitch")
+
+    # bump to a prerelease
+    util.run_cli("bump", "--prerelease", "rc", "--yes")
+    capsys.readouterr()
+
+    util.create_file_and_commit("fix: another fix")
+    util.create_file_and_commit("feat: more stuff")
+
+    # bump to stable
+    util.run_cli("bump", "--yes")
+    capsys.readouterr()
+
+    with pytest.raises(DryRunExit):
+        util.run_cli("changelog", "--dry-run")
+
+    out, _ = capsys.readouterr()
+    # The prerelease version (e.g. 0.2.0rc1) must not appear
+    assert "rc" not in out
+    # Commit messages from stable releases must be present
+    assert "add new output" in out
+    assert "more stuff" in out
+
+
+@pytest.mark.usefixtures("tmp_commitizen_project")
+def test_changelog_config_skip_prereleases_wins_over_merge_prerelease(
+    capsys: pytest.CaptureFixture,
+    config_path: Path,
+    util: UtilFixture,
+):
+    """When both skip_prereleases and merge_prerelease are set, skip wins."""
+    with config_path.open("a", encoding="utf-8") as f:
+        f.write("changelog_skip_prereleases = true\n")
+        f.write("changelog_merge_prerelease = true\n")
+
+    util.create_file_and_commit("feat: initial feature")
+    util.run_cli("bump", "--yes")
+    capsys.readouterr()
+
+    util.create_file_and_commit("feat: add new output")
+    util.run_cli("bump", "--prerelease", "alpha", "--yes")
+    capsys.readouterr()
+
+    util.create_file_and_commit("fix: another fix")
+    util.run_cli("bump", "--yes")
+    capsys.readouterr()
+
+    with pytest.raises(DryRunExit):
+        util.run_cli("changelog", "--dry-run")
+
+    out, _ = capsys.readouterr()
+    # Prerelease entries must not appear
+    assert "alpha" not in out
+    # Stable commit messages must be present
+    assert "add new output" in out
+    assert "another fix" in out
+
+
 @pytest.mark.usefixtures("tmp_commitizen_project")
 def test_changelog_config_start_rev_option(
     capsys: pytest.CaptureFixture,

tests/test_changelog.py

@@ -1191,6 +1191,41 @@ def test_generate_tree_from_commits_with_no_commits(tags):
     assert tuple(tree) == ({"changes": {}, "date": "", "version": "Unreleased"},)
 
 
+def test_generate_tree_from_commits_skip_prereleases(gitcommits, tags):
+    """skip_prereleases=True must omit all prerelease entries from the tree."""
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    rules = changelog.TagRules(skip_prereleases=True)
+    tree = list(
+        changelog.generate_tree_from_commits(
+            gitcommits, tags, parser, changelog_pattern, rules=rules
+        )
+    )
+    versions = [entry["version"] for entry in tree]
+    # Prerelease tags from TAGS: "1.0.0b2", "v1.0.0b1"
+    assert "1.0.0b2" not in versions
+    assert "v1.0.0b1" not in versions
+    # Stable releases must still be present
+    assert "v1.2.0" in versions
+    assert "v1.0.0" in versions
+
+
+def test_skip_prereleases_wins_over_merge_prereleases(gitcommits, tags):
+    """When both skip_prereleases and merge_prereleases are set, skip wins."""
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    rules = changelog.TagRules(skip_prereleases=True, merge_prereleases=True)
+    tree = list(
+        changelog.generate_tree_from_commits(
+            gitcommits, tags, parser, changelog_pattern, rules=rules
+        )
+    )
+    versions = [entry["version"] for entry in tree]
+    # Prereleases must be absent even though merge_prereleases=True
+    assert "1.0.0b2" not in versions
+    assert "v1.0.0b1" not in versions
+
+
 @pytest.mark.parametrize(
     ("change_type_order", "expected_reordering"),
     [
@@ -1651,35 +1686,69 @@ def test_tags_rules_get_version_tags(capsys: pytest.CaptureFixture):
 
 
 @pytest.mark.usefixtures("in_repo_root")
-def test_changelog_file_name_from_args_and_config():
+@pytest.mark.parametrize(
+    ("args_file_name", "config_file_name", "config_path", "expected"),
+    [
+        # CLI-provided --file-name: must be used as-is (relative to cwd).
+        # The config-dir anchor must NOT be applied.
+        (
+            "CUSTOM.md",
+            "CHANGELOG.md",
+            Path("/my/project/pyproject.toml"),
+            "CUSTOM.md",
+        ),
+        # Config-provided changelog_file: must be resolved relative to the
+        # config file's parent directory, not the cwd.
+        (
+            None,
+            "CHANGELOG.md",
+            Path("/my/project/pyproject.toml"),
+            Path("/my/project/CHANGELOG.md").as_posix(),
+        ),
+        # Nested config-provided path: still resolved relative to config dir.
+        (
+            None,
+            "docs/CHANGELOG.md",
+            Path("/my/project/pyproject.toml"),
+            Path("/my/project/docs/CHANGELOG.md").as_posix(),
+        ),
+        # CLI-provided nested path: used as-is (relative to cwd).
+        (
+            "changelog/CHANGES.rst",
+            "CHANGELOG.md",
+            Path("/my/project/pyproject.toml"),
+            "changelog/CHANGES.rst",
+        ),
+    ],
+)
+def test_changelog_file_name_resolution(
+    args_file_name: str | None,
+    config_file_name: str,
+    config_path: Path,
+    expected: str,
+):
+    """CLI --file-name is relative to cwd; config changelog_file is relative to
+    the config file's directory.  Fixes https://github.com/commitizen-tools/commitizen/issues/1411
+    """
     mock_config = Mock(spec=BaseConfig)
     mock_path = Mock(spec=Path)
-    mock_path.parent = Path("/my/project")
+    mock_path.parent = config_path.parent
     mock_config.path = mock_path
     mock_config.settings = {
         "name": "cz_conventional_commits",
-        "changelog_file": "CHANGELOG.md",
+        "changelog_file": config_file_name,
         "encoding": "utf-8",
-        "changelog_start_rev": "v1.0.0",
+        "changelog_start_rev": None,
         "tag_format": "$version",
         "legacy_tag_formats": [],
         "ignored_tag_formats": [],
-        "incremental": True,
-        "changelog_merge_prerelease": True,
+        "changelog_incremental": False,
+        "changelog_merge_prerelease": False,
     }
 
-    args = {
-        "file_name": "CUSTOM.md",
-        "unreleased_version": "1.0.1",
-    }
-    changelog = Changelog(mock_config, args)
-    assert (
-        Path(changelog.file_name).resolve() == Path("/my/project/CUSTOM.md").resolve()
-    )
+    args: dict = {"unreleased_version": "1.0.1"}
+    if args_file_name is not None:
+        args["file_name"] = args_file_name
 
-    args = {"unreleased_version": "1.0.1"}
-    changelog = Changelog(mock_config, args)
-    assert (
-        Path(changelog.file_name).resolve()
-        == Path("/my/project/CHANGELOG.md").resolve()
-    )
+    cl = Changelog(mock_config, args)  # type: ignore[arg-type]
+    assert cl.file_name == expected

tests/test_conf.py

@@ -100,6 +100,7 @@
     "changelog_incremental": False,
     "changelog_start_rev": None,
     "changelog_merge_prerelease": False,
+    "changelog_skip_prereleases": False,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,
@@ -140,6 +141,7 @@
     "changelog_incremental": False,
     "changelog_start_rev": None,
     "changelog_merge_prerelease": False,
+    "changelog_skip_prereleases": False,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,