feat(bump): added support for running arbitrary hooks during bump

To make commitizen integrate even better, new configuration keys hooks_pre_bump and hooks_post_bump were added to allow to run arbitrary commands prior to and right after running bump

Closes: #292

Author: skoef

commitizen/commands/bump.py

@@ -5,7 +5,7 @@
 import questionary
 from packaging.version import InvalidVersion, Version
 
-from commitizen import bump, cmd, defaults, factory, git, out
+from commitizen import bump, cmd, defaults, factory, git, hooks, out
 from commitizen.commands.changelog import Changelog
 from commitizen.config import BaseConfig
 from commitizen.exceptions import (
@@ -58,6 +58,8 @@ def __init__(self, config: BaseConfig, arguments: dict):
         self.no_verify = arguments["no_verify"]
         self.check_consistency = arguments["check_consistency"]
         self.retry = arguments["retry"]
+        self.hooks_pre_bump = self.config.settings["hooks_pre_bump"]
+        self.hooks_post_bump = self.config.settings["hooks_post_bump"]
 
     def is_initial_tag(self, current_tag_version: str, is_yes: bool = False) -> bool:
         """Check if reading the whole git tree up to HEAD is needed."""
@@ -272,6 +274,20 @@ def __call__(self):  # noqa: C901
 
         self.config.set_key("version", str(new_version))
 
+        if self.hooks_pre_bump:
+            hooks.run(
+                self.hooks_pre_bump,
+                _env_prefix="CZ_PRE_",
+                is_initial=is_initial,
+                current_version=current_version,
+                current_tag_version=current_tag_version,
+                new_version=new_version.public,
+                new_tag_version=new_tag_version,
+                message=message,
+                increment=increment,
+                changelog_file_name=changelog_cmd.file_name if self.changelog else None,
+            )
+
         if is_files_only:
             raise ExpectedExit()
 
@@ -300,6 +316,20 @@ def __call__(self):  # noqa: C901
         if c.return_code != 0:
             raise BumpTagFailedError(c.err)
 
+        if self.hooks_post_bump:
+            hooks.run(
+                self.hooks_post_bump,
+                _env_prefix="CZ_POST_",
+                was_initial=is_initial,
+                previous_version=current_version,
+                previous_tag_version=current_tag_version,
+                current_version=new_version.public,
+                current_tag_version=new_tag_version,
+                message=message,
+                increment=increment,
+                changelog_file_name=changelog_cmd.file_name if self.changelog else None,
+            )
+
         # TODO: For v3 output this only as diagnostic and remove this if
         if self.changelog_to_stdout:
             out.diagnostic("Done!")

commitizen/defaults.py

@@ -40,6 +40,8 @@ class Settings(TypedDict, total=False):
     style: Optional[List[Tuple[str, str]]]
     customize: CzSettings
     major_version_zero: bool
+    hooks_pre_bump: Optional[List[str]]
+    hooks_post_bump: Optional[List[str]]
 
 
 name: str = "cz_conventional_commits"
@@ -65,6 +67,8 @@ class Settings(TypedDict, total=False):
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,
+    "hooks_pre_bump": [],
+    "hooks_post_bump": [],
 }
 
 MAJOR = "MAJOR"

commitizen/exceptions.py

@@ -29,6 +29,7 @@ class ExitCode(enum.IntEnum):
     UNRECOGNIZED_CHARACTERSET_ENCODING = 22
     GIT_COMMAND_ERROR = 23
     INVALID_MANUAL_VERSION = 24
+    RUN_HOOK_FAILED = 25
 
 
 class CommitizenException(Exception):
@@ -163,3 +164,7 @@ class GitCommandError(CommitizenException):
 
 class InvalidManualVersion(CommitizenException):
     exit_code = ExitCode.INVALID_MANUAL_VERSION
+
+
+class RunHookError(CommitizenException):
+    exit_code = ExitCode.RUN_HOOK_FAILED

commitizen/hooks.py

@@ -0,0 +1,27 @@
+import os
+
+from commitizen import cmd, out
+from commitizen.exceptions import RunHookError
+
+
+def run(hooks, _env_prefix="CZ_", **env):
+    if isinstance(hooks, str):
+        hooks = [hooks]
+
+    for name, value in env.items():
+        name = _env_prefix + name.upper()
+        value = str(value) if value is not None else ""
+        os.environ[name] = value
+
+    for hook in hooks:
+        out.info(f"Running hook '{hook}'")
+
+        c = cmd.run(hook)
+
+        if c.out:
+            out.write(c.out)
+        if c.err:
+            out.error(c.err)
+
+        if c.return_code != 0:
+            raise RunHookError(f"Running hook '{hook}' failed")

docs/bump.md

@@ -411,6 +411,61 @@ Defaults to: `false`
 major_version_zero = true
 ```
 
+---
+
+### `hooks_pre_bump`
+
+A list of optional commands that will run right _after_ updating `version_files`
+and _before_ actual committing and tagging the release.
+
+Useful when you need to generate documentation based on the new version. During
+execution of the script, some environment variables are available:
+
+| Variable                     | Description                                                |
+| ---------------------------- | ---------------------------------------------------------- |
+| `CZ_PRE_IS_INITIAL`          | `True` when this is the initial release, `False` otherwise |
+| `CZ_PRE_CURRENT_VERSION`     | Current version, before the bump                           |
+| `CZ_PRE_CURRENT_TAG_VERSION` | Current version tag, before the bump                       |
+| `CZ_PRE_NEW_VERSION`         | New version, after the bump                                |
+| `CZ_PRE_NEW_TAG_VERSION`     | New version tag, after the bump                            |
+| `CZ_PRE_MESSAGE`             | Commit message of the bump                                 |
+| `CZ_PRE_INCREMENT`           | Whether this is a `MAJOR`, `MINOR` or `PATH` release       |
+| `CZ_PRE_CHANGELOG_FILE_NAME` | Path to the changelog file, if available                   |
+
+```toml
+[tool.commitizen]
+hooks_pre_bump = [
+  "scripts/generate_documentation.sh"
+]
+```
+
+---
+
+### `hooks_post_bump`
+
+A list of optional commands that will run right _after_ committing and tagging the release.
+
+Useful when you need to send notifications about a release, or further automate deploying the
+release. During execution of the script, some environment variables are available:
+
+| Variable                       | Description                                                 |
+| ------------------------------ | ----------------------------------------------------------- |
+| `CZ_POST_WAS_INITIAL`          | `True` when this was the initial release, `False` otherwise |
+| `CZ_POST_PREVIOUS_VERSION`     | Previous version, before the bump                           |
+| `CZ_POST_PREVIOUS_TAG_VERSION` | Previous version tag, before the bump                       |
+| `CZ_POST_CURRENT_VERSION`      | Current version, after the bump                             |
+| `CZ_POST_CURRENT_TAG_VERSION`  | Current version tag, after the bump                         |
+| `CZ_POST_MESSAGE`              | Commit message of the bump                                  |
+| `CZ_POST_INCREMENT`            | Whether this wass a `MAJOR`, `MINOR` or `PATH` release      |
+| `CZ_POST_CHANGELOG_FILE_NAME`  | Path to the changelog file, if available                    |
+
+```toml
+[tool.commitizen]
+hooks_post_bump = [
+  "scripts/slack_notification.sh"
+]
+```
+
 ## Custom bump
 
 Read the [customizing section](./customization.md).

tests/test_conf.py

@@ -19,6 +19,10 @@
     ["pointer", "reverse"],
     ["question", "underline"]
 ]
+hooks_pre_bump = [
+    "scripts/generate_documentation.sh"
+]
+hooks_post_bump = ["scripts/slack_notification.sh"]
 
 [tool.black]
 line-length = 88
@@ -31,6 +35,8 @@
         "version": "1.0.0",
         "version_files": ["commitizen/__version__.py", "pyproject.toml"],
         "style": [["pointer", "reverse"], ["question", "underline"]],
+        "hooks_pre_bump": ["scripts/generate_documentation.sh"],
+        "hooks_post_bump": ["scripts/slack_notification.sh"],
     }
 }
 
@@ -49,6 +55,8 @@
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,
+    "hooks_pre_bump": ["scripts/generate_documentation.sh"],
+    "hooks_post_bump": ["scripts/slack_notification.sh"],
 }
 
 _new_settings = {
@@ -65,6 +73,8 @@
     "update_changelog_on_bump": False,
     "use_shortcuts": False,
     "major_version_zero": False,
+    "hooks_pre_bump": ["scripts/generate_documentation.sh"],
+    "hooks_post_bump": ["scripts/slack_notification.sh"],
 }
 
 _read_settings = {
@@ -73,6 +83,8 @@
     "version_files": ["commitizen/__version__.py", "pyproject.toml"],
     "style": [["pointer", "reverse"], ["question", "underline"]],
     "changelog_file": "CHANGELOG.md",
+    "hooks_pre_bump": ["scripts/generate_documentation.sh"],
+    "hooks_post_bump": ["scripts/slack_notification.sh"],
 }