no-mistakes(document): Document bump_map no-bump rules

Author: bearomorphism

commitizen/version_increment.py

@@ -1,3 +1,12 @@
+"""Helpers for comparing and deriving semantic-version increments.
+
+This module centralizes the conversion between external increment labels and the
+ordered enum used internally by bump-related commands. The distinction matters
+because some callers intentionally coerce unknown values to ``NONE`` while
+matched ``bump_map`` outputs must preserve the historical fail-fast behavior for
+invalid custom rule values.
+"""
+
 from __future__ import annotations
 
 import re
@@ -20,6 +29,12 @@ class VersionIncrement(IntEnum):
     - PATCH: backwards-compatible bug fixes
     - MINOR: backwards-compatible features
     - MAJOR: incompatible API changes
+
+    Examples:
+        ```python
+        max([VersionIncrement.PATCH, VersionIncrement.MINOR])
+        # VersionIncrement.MINOR
+        ```
     """
 
     NONE = 0
@@ -33,7 +48,13 @@ def __str__(self) -> str:
 
     @classmethod
     def from_value(cls, value: object) -> VersionIncrement:
-        """Convert a possibly-invalid external value into a known increment."""
+        """Convert external increment input into a known increment.
+
+        This lenient path is used for inputs such as CLI arguments where an
+        unknown string should behave like "no increment" instead of raising.
+        Matched ``bump_map`` values are validated separately so custom rules keep
+        their historical fail-fast behavior.
+        """
         if not isinstance(value, str):
             return VersionIncrement.NONE
         try:

docs/customization/config_file.md

@@ -160,7 +160,7 @@ Example:
 | `schema_pattern`    | `str`  | `""`    | (OPTIONAL) The regular expression used to do commit message validation. Used by `cz check`.                                                                                                                                      |
 | `info_path`         | `str`  | `""`    | (OPTIONAL) The path to the file that contains explanation of the commit rules. Used by `cz info`. If not provided `cz info`, will load `info` instead.                                                                           |
 | `info`              | `str`  | `""`    | (OPTIONAL) Explanation of the commit rules. Used by `cz info`.                                                                                                                                                                   |
-| `bump_map`          | `dict` | `None`  | (OPTIONAL) Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`)                                                                                                                 |
+| `bump_map`          | `dict` | `None`  | (OPTIONAL) Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`). In JSON and YAML configs, `null` keeps a matched rule from bumping the version.                                  |
 | `bump_pattern`      | `str`  | `None`  | (OPTIONAL) Regex to extract information from commit (subject and body)                                                                                                                                                           |
 | `change_type_order` | `str`  | `None`  | (OPTIONAL) List of strings used to order the Changelog. All other types will be sorted alphabetically. Default is `["BREAKING CHANGE", "Feat", "Fix", "Refactor", "Perf"]`                                                       |
 | `commit_parser`     | `str`  | `None`  | (OPTIONAL) Regex to extract information used in creating changelog. [See more][changelog-spec]                                                                                                                                   |

docs/customization/python_class.md

@@ -99,7 +99,7 @@ You need to define 2 parameters inside your custom `BaseCommitizen`.
 | Parameter      | Type   | Default | Description                                                                                           |
 | -------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
 | `bump_pattern` | `str`  | `None`  | Regex to extract information from commit (subject and body)                                           |
-| `bump_map`     | `dict` | `None`  | Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`) |
+| `bump_map`     | `dict` | `None`  | Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`). Use `None` when a matched rule should not bump the version. |
 
 Let's see an example.
 

tests/commands/test_bump_command.py

@@ -1330,7 +1330,6 @@ def test_bump_allow_no_commit_with_no_eligible_commit(
     assert "bump: version 1.0.0 → 1.0.1" in out
 
 
-
 def test_bump_allow_no_commit_with_invalid_custom_bump_map_raises(
     tmp_commitizen_project: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1369,7 +1368,6 @@ def test_bump_allow_no_commit_with_invalid_custom_bump_map_raises(
     assert git.tag_exist("0.1.2") is False
 
 
-
 def test_bump_allow_no_commit_with_string_none_bump_map_raises(
     tmp_commitizen_project: Path,
     monkeypatch: pytest.MonkeyPatch,

tests/test_version_increment.py

@@ -221,7 +221,6 @@ def test_get_highest_by_messages_supports_custom_none_mapping() -> None:
     )
 
 
-
 def test_get_highest_by_messages_rejects_string_none_mapping() -> None:
     """The string NONE remains invalid at the bump-map computation boundary."""
     with pytest.raises(ValueError, match="NONE"):
@@ -232,7 +231,6 @@ def test_get_highest_by_messages_rejects_string_none_mapping() -> None:
         )
 
 
-
 def test_from_message_stops_after_major_match() -> None:
     """A major match on one line shields later invalid lines in that message."""
     assert (
@@ -245,7 +243,6 @@ def test_from_message_stops_after_major_match() -> None:
     )
 
 
-
 def test_get_highest_by_messages_raises_for_invalid_bump_map_value() -> None:
     """A matched custom bump-map value must fail instead of becoming NONE."""
     with pytest.raises(ValueError, match="MINORR"):
@@ -256,7 +253,6 @@ def test_get_highest_by_messages_raises_for_invalid_bump_map_value() -> None:
         )
 
 
-
 def test_get_highest_by_messages_compiles_pattern_once(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: