feat: add major-version-zero option to support initial package development

Author: jenstroeger

commitizen/cli.py

@@ -183,6 +183,12 @@
                         "default": False,
                         "help": "retry commit if it fails the 1st time",
                     },
+                    {
+                        "name": ["--major-version-zero"],
+                        "action": "store_true",
+                        "default": None,
+                        "help": "keep major version at zero, even for breaking changes",
+                    },
                     {
                         "name": "manual_version",
                         "type": str,

commitizen/commands/bump.py

@@ -5,7 +5,7 @@
 import questionary
 from packaging.version import InvalidVersion, Version
 
-from commitizen import bump, cmd, factory, git, out
+from commitizen import bump, cmd, defaults, factory, git, out
 from commitizen.commands.changelog import Changelog
 from commitizen.config import BaseConfig
 from commitizen.exceptions import (
@@ -45,6 +45,7 @@ def __init__(self, config: BaseConfig, arguments: dict):
                     "bump_message",
                     "gpg_sign",
                     "annotated_tag",
+                    "major_version_zero",
                 ]
                 if arguments[key] is not None
             },
@@ -101,6 +102,7 @@ def __call__(self):  # noqa: C901
         tag_format: str = self.bump_settings["tag_format"]
         bump_commit_message: str = self.bump_settings["bump_message"]
         version_files: List[str] = self.bump_settings["version_files"]
+        major_version_zero: bool = self.bump_settings["major_version_zero"]
 
         dry_run: bool = self.arguments["dry_run"]
         is_yes: bool = self.arguments["yes"]
@@ -126,6 +128,20 @@ def __call__(self):  # noqa: C901
                     "--local-version cannot be combined with MANUAL_VERSION"
                 )
 
+            if major_version_zero:
+                raise NotAllowed(
+                    "--major-version-zero cannot be combined with MANUAL_VERSION"
+                )
+
+        if major_version_zero:
+            if not current_version.startswith("0."):
+                raise NotAllowed(
+                    f"--major-version-zero is meaningless for current version {current_version}"
+                )
+
+            # Update the bump map to ensure major version doesn't increment.
+            self.cz.bump_map = defaults.bump_map_major_version_zero
+
         current_tag_version: str = bump.normalize_tag(
             current_version, tag_format=tag_format
         )

commitizen/defaults.py

@@ -39,6 +39,7 @@ class Settings(TypedDict, total=False):
     use_shortcuts: bool
     style: Optional[List[Tuple[str, str]]]
     customize: CzSettings
+    major_version_zero: bool
 
 
 name: str = "cz_conventional_commits"
@@ -63,6 +64,7 @@ class Settings(TypedDict, total=False):
     "changelog_start_rev": None,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
+    "major_version_zero": False,
 }
 
 MAJOR = "MAJOR"
@@ -80,6 +82,16 @@ class Settings(TypedDict, total=False):
         (r"^perf", PATCH),
     )
 )
+bump_map_major_version_zero = OrderedDict(
+    (
+        (r"^.+!$", MINOR),
+        (r"^BREAKING[\-\ ]CHANGE", MINOR),
+        (r"^feat", MINOR),
+        (r"^fix", PATCH),
+        (r"^refactor", PATCH),
+        (r"^perf", PATCH),
+    )
+)
 change_type_order = ["BREAKING CHANGE", "Feat", "Fix", "Refactor", "Perf"]
 bump_message = "bump: version $current_version → $new_version"
 

docs/bump.md

@@ -59,7 +59,8 @@ usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
                [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
                [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
                [--check-consistency] [--annotated-tag] [--gpg-sign]
-               [--changelog-to-stdout] [--retry] [MANUAL_VERSION]
+               [--changelog-to-stdout] [--retry] [--major-version-zero]
+               [MANUAL_VERSION]
 
 positional arguments:
   MANUAL_VERSION        bump to the given version (e.g: 1.5.3)
@@ -93,6 +94,7 @@ options:
   --changelog-to-stdout
                         Output changelog to the stdout
   --retry               retry commit if it fails the 1st time
+  --major-version-zero  keep major version at zero, even for breaking changes
 ```
 
 ### `--files-only`
@@ -199,6 +201,18 @@ It will retry the commit if it fails the 1st time.
 
 Useful to combine with code formatters, like [Prettier](https://prettier.io/).
 
+### `--major-version-zero`
+
+A project in its initial development should have a major version zero, and even breaking changes
+should not bump that major version from zero. This command ensures that behavior.
+
+If `--major-version-zero` is used for projects that have a version number greater than zero it fails.
+If used together with a manual version the command also fails.
+
+We recommend setting `major_version_zero = true` in your configuration file while a project
+is in its initial development. Remove that configuration using a breaking-change commit to bump
+your project’s major version to `v1.0.0` once your project has reached maturity.
+
 ## Avoid raising errors
 
 Some situations from commitizen rise an exit code different than 0.
@@ -369,6 +383,8 @@ When set to `true` commitizen will create annotated tags.
 
 ```toml
 [tool.commitizen]
+annotated_tag = true
+```
 
 ---
 
@@ -379,7 +395,20 @@ When set to `true` commitizen will create gpg signed tags.
 ```toml
 [tool.commitizen]
 gpg_sign = true
-annotated_tag = true
+```
+
+---
+
+### `major_version_zero`
+
+When set to `true` commitizen will keep the major version at zero.
+Useful during the initial development stage of your project.
+
+Defaults to: `false`
+
+```toml
+[tool.commitizen]
+major_version_zero = true
 ```
 
 ## Custom bump

tests/commands/test_bump_command.py

@@ -22,7 +22,7 @@
     NotAllowed,
     NoVersionSpecifiedError,
 )
-from tests.utils import create_file_and_commit
+from tests.utils import create_file_and_commit, create_tag
 
 
 @pytest.mark.parametrize(
@@ -151,6 +151,31 @@ def test_bump_major_increment(commit_msg, mocker):
     assert tag_exists is True
 
 
+@pytest.mark.usefixtures("tmp_commitizen_project")
+@pytest.mark.parametrize(
+    "commit_msg",
+    (
+        "feat: new user interface\n\nBREAKING CHANGE: age is no longer supported",
+        "feat!: new user interface\n\nBREAKING CHANGE: age is no longer supported",
+        "feat!: new user interface",
+        "feat(user): new user interface\n\nBREAKING CHANGE: age is no longer supported",
+        "feat(user)!: new user interface\n\nBREAKING CHANGE: age is no longer supported",
+        "feat(user)!: new user interface",
+        "BREAKING CHANGE: age is no longer supported",
+        "BREAKING-CHANGE: age is no longer supported",
+    ),
+)
+def test_bump_major_increment_major_version_zero(commit_msg, mocker):
+    create_file_and_commit(commit_msg)
+
+    testargs = ["cz", "bump", "--yes", "--major-version-zero"]
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    tag_exists = git.tag_exist("0.2.0")
+    assert tag_exists is True
+
+
 @pytest.mark.usefixtures("tmp_commitizen_project")
 @pytest.mark.parametrize(
     "commit_msg,increment,expected_tag",
@@ -320,6 +345,34 @@ def test_bump_when_version_inconsistent_in_version_files(
     assert partial_expected_error_message in str(excinfo.value)
 
 
+def test_bump_major_version_zero_when_major_is_not_zero(mocker, tmp_commitizen_project):
+    tmp_version_file = tmp_commitizen_project.join("__version__.py")
+    tmp_version_file.write("1.0.0")
+    tmp_commitizen_cfg_file = tmp_commitizen_project.join("pyproject.toml")
+    tmp_commitizen_cfg_file.write(
+        f"[tool.commitizen]\n"
+        'version="1.0.0"\n'
+        f'version_files = ["{str(tmp_version_file)}"]'
+    )
+    tmp_changelog_file = tmp_commitizen_project.join("CHANGELOG.md")
+    tmp_changelog_file.write("## v1.0.0")
+
+    create_file_and_commit("feat(user): new file")
+    create_tag("v1.0.0")
+    create_file_and_commit("feat(user)!: new file")
+
+    testargs = ["cz", "bump", "--yes", "--major-version-zero"]
+    mocker.patch.object(sys, "argv", testargs)
+
+    with pytest.raises(NotAllowed) as excinfo:
+        cli.main()
+
+    expected_error_message = (
+        "--major-version-zero is meaningless for current version 1.0.0"
+    )
+    assert expected_error_message in str(excinfo.value)
+
+
 def test_bump_files_only(mocker, tmp_commitizen_project):
     tmp_version_file = tmp_commitizen_project.join("__version__.py")
     tmp_version_file.write("0.1.0")
@@ -683,3 +736,20 @@ def test_bump_manual_version(mocker, manual_version):
     cli.main()
     tag_exists = git.tag_exist(manual_version)
     assert tag_exists is True
+
+
+@pytest.mark.usefixtures("tmp_commitizen_project")
+def test_bump_manual_version_disallows_major_version_zero(mocker):
+    create_file_and_commit("feat: new file")
+
+    manual_version = "0.2.0"
+    testargs = ["cz", "bump", "--yes", "--major-version-zero", manual_version]
+    mocker.patch.object(sys, "argv", testargs)
+
+    with pytest.raises(NotAllowed) as excinfo:
+        cli.main()
+
+    expected_error_message = (
+        "--major-version-zero cannot be combined with MANUAL_VERSION"
+    )
+    assert expected_error_message in str(excinfo.value)

tests/test_conf.py

@@ -48,6 +48,7 @@
     "changelog_start_rev": None,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
+    "major_version_zero": False,
 }
 
 _new_settings = {
@@ -63,6 +64,7 @@
     "changelog_start_rev": None,
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
+    "major_version_zero": False,
 }
 
 _read_settings = {

tests/utils.py

@@ -26,6 +26,12 @@ def create_file_and_commit(message: str, filename: Optional[str] = None):
         raise exceptions.CommitError(c.err)
 
 
+def create_tag(tag: str):
+    c = git.tag(tag)
+    if c.return_code != 0:
+        raise exceptions.CommitError(c.err)
+
+
 def wait_for_tag():
     """Wait for tag.