docs: add info about creating hooks

Author: woile

docs/changelog.md

@@ -124,10 +124,15 @@ Benefits:
 cz changelog --incremental
 ```
 
-## TODO
+## Hooks
 
-- [ ] support for hooks: this would allow introduction of custom information in the commiter, like a github or jira url. Eventually we could build a `CzConventionalGithub`, which would add links to commits
-- [x] support for map: allow the usage of a `change_type` mapper, to convert from feat to feature for example.
+Supported hook methods:
+
+- per parsed message: useful to add links
+- end of changelog generation: useful to send slack or chat message, or notify another department
+
+Read more about hooks in the [customization page][customization]
 
 [keepachangelog]: https://keepachangelog.com/
 [semver]: https://semver.org/
+[customization]: ./customization.md

docs/customization.md

@@ -137,12 +137,52 @@ cz -n cz_strange bump
 The changelog generator should just work in a very basic manner without touching anything.
 You can customize it of course, and this are the variables you need to add to your custom `BaseCommitizen`.
 
-| Parameter           | Type                                    | Required | Description                                                                                                                                         |
-| ------------------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `commit_parser`     | `str`                                   | NO       | Regex which should provide the variables explained in the [changelog description][changelog-des]                                                    |
-| `changelog_pattern` | `str`                                   | NO       | Regex to validate the commits, this is useful to skip commits that don't meet your rulling standards like a Merge. Usually the same as bump_pattern |
-| `change_type_map`   | `dict`                                  | NO       | Convert the title of the change type that will appear in the changelog, if a value is not found, the original will be provided                      |
-| `message_hook`      | `method: (dict, git.GitCommit) -> dict` | NO       | Customize with extra information your message output, like adding links, this function is executed per parsed commit.                               |
+| Parameter           | Type                                                                     | Required | Description                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `commit_parser`     | `str`                                                                    | NO       | Regex which should provide the variables explained in the [changelog description][changelog-des]                                                                |
+| `changelog_pattern` | `str`                                                                    | NO       | Regex to validate the commits, this is useful to skip commits that don't meet your rulling standards like a Merge. Usually the same as bump_pattern             |
+| `change_type_map`   | `dict`                                                                   | NO       | Convert the title of the change type that will appear in the changelog, if a value is not found, the original will be provided                                  |
+| `message_hook`      | `method: (dict, git.GitCommit) -> dict`                                  | NO       | Customize with extra information your message output, like adding links, this function is executed per parsed commit.                                           |
+| `changelog_hook`    | `method: (full_changelog: str, partial_changelog: Optional[str]) -> str` | NO       | Receives the whole and partial (if used incremental) changelog. Useful to send slack messages or notify a compliance department. Must return the full_changelog |
+
+```python
+from commitizen.cz.base import BaseCommitizen
+import chat
+import compliance
+
+class StrangeCommitizen(BaseCommitizen):
+    changelog_pattern = r"^(break|new|fix|hotfix)"
+    commit_parser = r"^(?P<change_type>feat|fix|refactor|perf|BREAKING CHANGE)(?:\((?P<scope>[^()\r\n]*)\)|\()?(?P<breaking>!)?:\s(?P<message>.*)?"
+    change_type_map = {
+        "feat": "Features",
+        "fix": "Bug Fixes",
+        "refactor": "Code Refactor",
+        "perf": "Performance improvements"
+    }
+
+    def message_hook(self, parsed_message: dict, commit: git.GitCommit) -> dict:
+        rev = commit.rev
+        m = parsed_message["message"]
+        parsed_message["message"] = f"{m} {rev}"
+        return parsed_message
+
+    def changelog_hook(self, full_changelog: str, partial_changelog: Optional[str]) -> str:
+        """Executed at the end of the changelog generation
+
+        full_changelog: it's the output about to being written into the file
+        partial_changelog: it's the new stuff, this is useful to send slack messages or
+                           similar
+
+        Return:
+            the new updated full_changelog
+        """
+        if partial_changelog:
+            chat.room("#commiters").notify(partial_changelog)
+        if full_changelog:
+            compliance.send(full_changelog)
+        full_changelog.replace(' fix ', ' **fix** ')
+        return full_changelog
+```
 
 [changelog-des]: ./changelog.md#description
 

tests/commands/test_changelog_command.py

@@ -247,7 +247,7 @@ def test_changlog_hook(mocker, config):
     create_file_and_commit("Merge into master")
 
     changelog = Changelog(
-        config, {"unreleased_version": None, "incremental": True, "dry_run": False,},
+        config, {"unreleased_version": None, "incremental": True, "dry_run": False},
     )
     mocker.patch.object(changelog.cz, "changelog_hook", changelog_hook_mock)
     changelog()