fix(bump): change --exact-increment to --increment-mode

This provides some future proofing for implementing new version progression behaviors

Author: chadrik

Diff for: commitizen/cli.py

@@ -231,13 +231,16 @@ def __call__(
                         "type": str.upper,
                     },
                     {
-                        "name": ["--exact-increment"],
-                        "action": "store_true",
+                        "name": ["--increment-mode"],
+                        "choices": ["linear", "exact"],
+                        "default": "linear",
                         "help": (
-                            "apply the exact changes that have been specified (or "
-                            "determined from the commit log), disabling logic that "
-                            "guesses the next version based on typical version "
-                            "progression when a prelease suffix is present."
+                            "set the method by which the new version is chosen. "
+                            "'linear' (default) guesses the next version based on typical linear version progression, "
+                            "such that bumping of a pre-release with lower precedence than the current pre-release "
+                            "phase maintains the current phase of higher precedence. "
+                            "'exact' applies the changes that have been specified (or determined from the commit log) "
+                            "without interpretation, such that the increment and pre-release are always honored"
                         ),
                     },
                     {

Diff for: commitizen/commands/bump.py

@@ -52,7 +52,7 @@ def __init__(self, config: BaseConfig, arguments: dict):
                     "tag_format",
                     "prerelease",
                     "increment",
-                    "exact_increment",
+                    "increment_mode",
                     "bump_message",
                     "gpg_sign",
                     "annotated_tag",
@@ -159,7 +159,7 @@ def __call__(self) -> None:  # noqa: C901
         is_local_version: bool = self.arguments["local_version"]
         manual_version = self.arguments["manual_version"]
         build_metadata = self.arguments["build_metadata"]
-        exact_increment: bool = self.arguments["exact_increment"]
+        increment_mode: str = self.arguments["increment_mode"]
 
         if manual_version:
             if increment:
@@ -254,7 +254,7 @@ def __call__(self) -> None:  # noqa: C901
                 devrelease=devrelease,
                 is_local_version=is_local_version,
                 build_metadata=build_metadata,
-                exact_increment=exact_increment,
+                exact_increment=increment_mode == "exact",
             )
 
         new_tag_version = bump.normalize_tag(

Diff for: docs/bump.md

@@ -79,7 +79,12 @@ options:
                         specify non-negative integer for dev. release
   --increment {MAJOR,MINOR,PATCH}
                         manually specify the desired increment
-  --exact-increment     apply the exact changes that have been specified (or determined from the commit log), disabling logic that guesses the next version based on typical version progression when a prelease suffix is present.
+  --increment-mode
+                        set the method by which the new version is chosen. 'linear' (default) guesses the next version based
+                        on typical linear version progression, such that bumping of a pre-release with lower precedence than
+                        the current pre-release phase maintains the current phase of higher precedence. 'exact' applies the
+                        changes that have been specified (or determined from the commit log) without interpretation, such that
+                        the increment and pre-release are always honored
   --check-consistency, -cc
                         check consistency among versions defined in commitizen configuration and version_files
   --annotated-tag, -at  create annotated tag instead of lightweight one
@@ -140,29 +145,27 @@ by their precedence and showcase how a release might flow through a development
 - `1.1.0rc0` after bumping the release candidate
 - `1.1.0` next feature release
 
-Also note that bumping pre-releases _maintains linearity_: bumping of a pre-release with lower precedence than
-the current pre-release phase maintains the current phase of higher precedence. For example, if the current
-version is `1.0.0b1` then bumping with `--prerelease alpha` will continue to bump the “beta” phase.
-This behavior can be overridden by passing `--exact-increment` (see below).
+### `--increment-mode`
 
-### `--exact-increment`
+By default, `--increment-mode` is set to `linear`, which ensures taht bumping pre-releases _maintains linearity_: 
+bumping of a pre-release with lower precedence than the current pre-release phase maintains the current phase of 
+higher precedence. For example, if the current version is `1.0.0b1` then bumping with `--prerelease alpha` will 
+continue to bump the “beta” phase.
 
-The `--exact-increment` flag bypasses the logic that creates a best guess for the next version based on the
-principle of maintaining linearity when a pre-release is present (see above).  Instead, `bump` will apply the 
+Setting `--increment-mode` to `exact` instructs `cz bump` to instead apply the 
 exact changes that have been specified with `--increment` or determined from the commit log. For example, 
 `--prerelease beta` will always result in a `b` tag, and `--increment PATCH` will always increase the patch component.
 
 Below are some examples that illustrate the difference in behavior:
 
-
-| Increment | Pre-release | Start Version | Without `--exact-increment` | With `--exact-increment` |
-|-----------|-------------|---------------|-----------------------------|--------------------------|
-| `MAJOR`   |             | `2.0.0b0`     | `2.0.0`                     | `3.0.0`                  |
-| `MINOR`   |             | `2.0.0b0`     | `2.0.0`                     | `2.1.0`                  |
-| `PATCH`   |             | `2.0.0b0`     | `2.0.0`                     | `2.0.1`                  |
-| `MAJOR`   | `alpha`     | `2.0.0b0`     | `3.0.0a0`                   | `3.0.0a0`                |
-| `MINOR`   | `alpha`     | `2.0.0b0`     | `2.0.0b1`                   | `2.1.0a0`                |
-| `PATCH`   | `alpha`     | `2.0.0b0`     | `2.0.0b1`                   | `2.0.1a0`                |
+| Increment | Pre-release | Start Version | `--increment-mode=linear` | `--increment-mode=exact` |
+|-----------|-------------|---------------|---------------------------|--------------------------|
+| `MAJOR`   |             | `2.0.0b0`     | `2.0.0`                   | `3.0.0`                  |
+| `MINOR`   |             | `2.0.0b0`     | `2.0.0`                   | `2.1.0`                  |
+| `PATCH`   |             | `2.0.0b0`     | `2.0.0`                   | `2.0.1`                  |
+| `MAJOR`   | `alpha`     | `2.0.0b0`     | `3.0.0a0`                 | `3.0.0a0`                |
+| `MINOR`   | `alpha`     | `2.0.0b0`     | `2.0.0b1`                 | `2.1.0a0`                |
+| `PATCH`   | `alpha`     | `2.0.0b0`     | `2.0.0b1`                 | `2.0.1a0`                |
 
 ### `--check-consistency`
 

Diff for: tests/commands/test_bump_command.py

@@ -327,34 +327,48 @@ def test_bump_command_prelease_exact_mode(mocker: MockFixture):
     assert tag_exists is True
 
     # PRERELEASE + PATCH BUMP
-    testargs = ["cz", "bump", "--prerelease", "alpha", "--yes", "--exact-increment"]
+    testargs = [
+        "cz",
+        "bump",
+        "--prerelease",
+        "alpha",
+        "--yes",
+        "--increment-mode=exact",
+    ]
     mocker.patch.object(sys, "argv", testargs)
     cli.main()
 
     tag_exists = git.tag_exist("0.2.0a1")
     assert tag_exists is True
 
     # PRERELEASE + MINOR BUMP
-    # --exact-increment allows the minor version to bump, and restart the prerelease
+    # --increment-mode allows the minor version to bump, and restart the prerelease
     create_file_and_commit("feat: location")
 
-    testargs = ["cz", "bump", "--prerelease", "alpha", "--yes", "--exact-increment"]
+    testargs = [
+        "cz",
+        "bump",
+        "--prerelease",
+        "alpha",
+        "--yes",
+        "--increment-mode=exact",
+    ]
     mocker.patch.object(sys, "argv", testargs)
     cli.main()
 
     tag_exists = git.tag_exist("0.3.0a0")
     assert tag_exists is True
 
     # PRERELEASE + MAJOR BUMP
-    # --exact-increment allows the major version to bump, and restart the prerelease
+    # --increment-mode=exact allows the major version to bump, and restart the prerelease
     testargs = [
         "cz",
         "bump",
         "--prerelease",
         "alpha",
         "--yes",
         "--increment=MAJOR",
-        "--exact-increment",
+        "--increment-mode=exact",
     ]
     mocker.patch.object(sys, "argv", testargs)
     cli.main()