feat: Add option to enable/disable "zerover" behavior

Issue #57: #57
PR #58: #58
Co-authored-by: Timothée Mazzucotelli <pawamoy@pm.me>

README.md

@@ -155,6 +155,9 @@ options:
                         for 0.x versions), else if there are new features,
                         bump the minor number, else just bump the patch number.
                         Default: None.
+  -Z, --no-zerover      By default, breaking changes on a 0.x don't bump the
+                        major version, maintaining it at 0. With this option, a
+                        breaking change will bump a 0.x version to 1.0.
   -h, --help            Show this help message and exit.
   -i, --in-place        Insert new entries (versions missing from changelog)
                         in-place. An output file must be specified. With

docs/usage.md

@@ -276,20 +276,31 @@ git-changelog --bump minor  # 1.2.3 -> 1.3.0
 git-changelog --bump patch  # 1.2.3 -> 1.2.4
 ```
 
-Note that the major number won't be bumped if the latest version is 0.x.
+Note that, by default the major number won't be bumped if the latest version is 0.x.
 Instead, the minor number will be bumped:
 
 ```bash
 git-changelog --bump major  # 0.1.2 -> 0.2.0, same as minor because 0.x
 git-changelog --bump minor  # 0.1.2 -> 0.2.0
 ```
 
-In that case, when you are ready to bump to 1.0.0, just pass this version as value:
+In that case, when you are ready to bump to 1.0.0,
+just pass this version as value, or use the `-Z`, `--no-zerover` flag:
 
 ```bash
 git-changelog --bump 1.0.0
+git-changelog --bump auto --no-zerover
+git-changelog --bump major --no-zerover
 ```
 
+If you use *git-changelog* in CI, to update your changelog automatically,
+it is recommended to use a configuration file instead of the CLI option.
+On a fresh project, start by setting `zerover = true` in one of the supported
+[configuration files](#configuration-files). Then, once you are ready
+to bump to v1, set `zerover = false` and commit it as a breaking change.
+Once v1 is released, the setting has no use anymore, and you can remove it
+from your configuration file.
+
 ## Parse additional information in commit messages
 
 *git-changelog* is able to parse the body of commit messages
@@ -518,6 +529,8 @@ repository = "."
 sections = ["fix", "maint"]
 template = "angular"
 version-regex = "^## \\\\[(?P<version>v?[^\\\\]]+)"
+provider = "gitlab"
+zerover = true
 ```
 
 In the case of configuring *git-changelog* within `pyproject.toml`, these

src/git_changelog/build.py

@@ -27,12 +27,13 @@
 ConventionType = Union[str, CommitConvention, Type[CommitConvention]]
 
 
-def bump(version: str, part: Literal["major", "minor", "patch"] = "patch") -> str:
+def bump(version: str, part: Literal["major", "minor", "patch"] = "patch", *, zerover: bool = True) -> str:
     """Bump a version.
 
     Arguments:
         version: The version to bump.
         part: The part of the version to bump (major, minor, or patch).
+        zerover: Keep major version at zero, even for breaking changes.
 
     Returns:
         The bumped version.
@@ -43,7 +44,7 @@ def bump(version: str, part: Literal["major", "minor", "patch"] = "patch") -> st
         version = version[1:]
 
     semver_version = VersionInfo.parse(version)
-    if part == "major" and semver_version.major != 0:
+    if part == "major" and (semver_version.major != 0 or not zerover):
         semver_version = semver_version.bump_major()
     elif part == "minor" or (part == "major" and semver_version.major == 0):
         semver_version = semver_version.bump_minor()
@@ -170,6 +171,7 @@ def __init__(
         sections: list[str] | None = None,
         bump_latest: bool = False,
         bump: str | None = None,
+        zerover: bool = True,
         filter_commits: str | None = None,
     ):
         """Initialization method.
@@ -183,11 +185,13 @@ def __init__(
             sections: The sections to render (features, bug fixes, etc.).
             bump_latest: Deprecated, use `bump="auto"` instead. Whether to try and bump latest version to guess new one.
             bump: Whether to try and bump to a given version.
+            zerover: Keep major version at zero, even for breaking changes.
             filter_commits: The Git revision-range used to filter commits in git-log (e.g: `v1.0.1..`).
         """
         self.repository: str | Path = repository
         self.parse_provider_refs: bool = parse_provider_refs
         self.parse_trailers: bool = parse_trailers
+        self.zerover: bool = zerover
         self.filter_commits: str | None = filter_commits
 
         # set provider
@@ -423,7 +427,7 @@ def _bump(self, version: str) -> None:
             if version in {"major", "minor", "patch"}:
                 # bump version (don't fail on non-semver versions)
                 try:
-                    last_version.planned_tag = bump(last_tag, version)  # type: ignore[arg-type]
+                    last_version.planned_tag = bump(last_tag, version, zerover=self.zerover)  # type: ignore[arg-type]
                 except ValueError:
                     return
             else:

src/git_changelog/cli.py

@@ -71,6 +71,7 @@
     "sections": None,
     "template": "keepachangelog",
     "version_regex": DEFAULT_VERSION_REGEX,
+    "zerover": True,
 }
 
 
@@ -306,12 +307,20 @@ def get_parser() -> argparse.ArgumentParser:
         dest="omit_empty_versions",
         help="Omit empty versions from the output. Default: unset (false).",
     )
+    parser.add_argument(
+        "-Z",
+        "--no-zerover",
+        action="store_false",
+        dest="zerover",
+        help="By default, breaking changes on a 0.x don't bump the major version, maintaining it at 0. "
+        "With this option, a breaking change will bump a 0.x version to 1.0.",
+    )
     parser.add_argument(
         "-F",
         "--filter-commits",
         action="store",
         dest="filter_commits",
-        help="The Git revision-range filter to use (e.g. 'v1.2.0..'). Default: no filter",
+        help="The Git revision-range filter to use (e.g. 'v1.2.0..'). Default: no filter.",
     )
     parser.add_argument(
         "-V",
@@ -465,6 +474,7 @@ def build_and_render(
     omit_empty_versions: bool = False,  # noqa: FBT001,FBT002
     provider: str | None = None,
     bump: str | None = None,
+    zerover: bool = True,  # noqa: FBT001,FBT002
     filter_commits: str | None = None,
 ) -> tuple[Changelog, str]:
     """Build a changelog and render it.
@@ -488,6 +498,7 @@ def build_and_render(
         omit_empty_versions: Whether to omit empty versions from the output.
         provider: Provider class used by this repository.
         bump: Whether to try and bump to a given version.
+        zerover: Keep major version at zero, even for breaking changes.
         filter_commits: The Git revision-range used to filter commits in git-log.
 
     Raises:
@@ -531,6 +542,7 @@ def build_and_render(
         parse_trailers=parse_trailers,
         sections=sections,
         bump=bump,
+        zerover=zerover,
         filter_commits=filter_commits,
     )
 

tests/test_version.py

@@ -65,6 +65,35 @@ def test_bump_minor(version: str, bumped: str) -> None:
     assert bump(version, "minor") == bumped
 
 
+@pytest.mark.parametrize(
+    ("version", "bumped"),
+    [
+        ("0.0.1", "1.0.0"),
+        ("0.1.0", "1.0.0"),
+        ("0.1.1", "1.0.0"),
+        ("1.0.0", "2.0.0"),
+        ("1.0.1", "2.0.0"),
+        ("1.1.0", "2.0.0"),
+        ("1.1.1", "2.0.0"),
+        ("v0.0.1", "v1.0.0"),
+        ("v0.1.0", "v1.0.0"),
+        ("v0.1.1", "v1.0.0"),
+        ("v1.0.0", "v2.0.0"),
+        ("v1.0.1", "v2.0.0"),
+        ("v1.1.0", "v2.0.0"),
+        ("v1.1.1", "v2.0.0"),
+    ],
+)
+def test_bump_major_no_zerover(version: str, bumped: str) -> None:
+    """Test major version bumping without zerover.
+
+    Parameters:
+        version: The base version.
+        bumped: The expected, bumped version.
+    """
+    assert bump(version, "major", zerover=False) == bumped
+
+
 @pytest.mark.parametrize(
     ("version", "bumped"),
     [
@@ -84,11 +113,11 @@ def test_bump_minor(version: str, bumped: str) -> None:
         ("v1.1.1", "v2.0.0"),
     ],
 )
-def test_bump_major(version: str, bumped: str) -> None:
-    """Test major version bumping.
+def test_bump_major_zerover(version: str, bumped: str) -> None:
+    """Test major version bumping with zerover.
 
     Parameters:
         version: The base version.
         bumped: The expected, bumped version.
     """
-    assert bump(version, "major") == bumped
+    assert bump(version, "major", zerover=True) == bumped