feat(template): allow to override the template from cli, configuration and plugins

Fixes #132
Fixes #384
Fixes #433
Closes #376
Closes #640

Author: noirbizarre

commitizen/changelog.py

@@ -32,7 +32,13 @@
 from datetime import date
 from typing import TYPE_CHECKING, Callable, Iterable, cast
 
-from jinja2 import Environment, PackageLoader
+from jinja2 import (
+    BaseLoader,
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+)
 
 from commitizen import out
 from commitizen.bump import normalize_tag
@@ -49,6 +55,8 @@
 if TYPE_CHECKING:
     from commitizen.version_schemes import VersionScheme
 
+DEFAULT_TEMPLATE = "keep_a_changelog_template.j2"
+
 
 def get_commit_tag(commit: GitCommit, tags: list[GitTag]) -> GitTag | None:
     return next((tag for tag in tags if tag.rev == commit.rev), None)
@@ -187,11 +195,18 @@ def order_changelog_tree(tree: Iterable, change_type_order: list[str]) -> Iterab
     return sorted_tree
 
 
-def render_changelog(tree: Iterable) -> str:
-    loader = PackageLoader("commitizen", "templates")
+def render_changelog(
+    tree: Iterable,
+    loader: BaseLoader | None = None,
+    template: str | None = None,
+    **kwargs,
+) -> str:
+    loader = ChoiceLoader(
+        [FileSystemLoader("."), loader or PackageLoader("commitizen", "templates")]
+    )
     env = Environment(loader=loader, trim_blocks=True)
-    jinja_template = env.get_template("keep_a_changelog_template.j2")
-    changelog: str = jinja_template.render(tree=tree)
+    jinja_template = env.get_template(template or DEFAULT_TEMPLATE)
+    changelog: str = jinja_template.render(tree=tree, **kwargs)
     return changelog
 
 

commitizen/cli.py

@@ -3,6 +3,7 @@
 import argparse
 import logging
 import sys
+from copy import deepcopy
 from functools import partial
 from pathlib import Path
 from types import TracebackType
@@ -20,6 +21,51 @@
 )
 
 logger = logging.getLogger(__name__)
+
+
+class ParseKwargs(argparse.Action):
+    """
+    Parse arguments in the for `key=value`.
+
+    Quoted strings are automatically unquoted.
+    Can be submitted multiple times:
+
+    ex:
+        -k key=value -k double-quotes="value" -k single-quotes='value'
+
+        will result in
+
+        namespace["opt"] == {
+            "key": "value",
+            "double-quotes": "value",
+            "single-quotes": "value",
+        }
+    """
+
+    def __call__(self, parser, namespace, kwarg, option_string=None):
+        kwargs = getattr(namespace, self.dest, None) or {}
+        key, value = kwarg.split("=", 1)
+        kwargs[key] = value.strip("'\"")
+        setattr(namespace, self.dest, kwargs)
+
+
+tpl_arguments = (
+    {
+        "name": ["--template", "-t"],
+        "help": (
+            "changelog template file name "
+            "(relative to the current working directory)"
+        ),
+    },
+    {
+        "name": ["--extra", "-e"],
+        "action": ParseKwargs,
+        "dest": "extras",
+        "metavar": "EXTRA",
+        "help": "a changelog extra variable (in the form 'key=value')",
+    },
+)
+
 data = {
     "prog": "cz",
     "description": (
@@ -210,6 +256,7 @@
                         "default": None,
                         "help": "keep major version at zero, even for breaking changes",
                     },
+                    *deepcopy(tpl_arguments),
                     {
                         "name": ["--prerelease-offset"],
                         "type": int,
@@ -299,6 +346,7 @@
                         "default": None,
                         "choices": version_schemes.KNOWN_SCHEMES,
                     },
+                    *deepcopy(tpl_arguments),
                 ],
             },
             {

commitizen/commands/bump.py

@@ -51,6 +51,7 @@ def __init__(self, config: BaseConfig, arguments: dict):
                     "annotated_tag",
                     "major_version_zero",
                     "prerelease_offset",
+                    "template",
                 ]
                 if arguments[key] is not None
             },
@@ -77,6 +78,8 @@ def __init__(self, config: BaseConfig, arguments: dict):
         self.scheme = get_version_scheme(
             self.config, arguments["version_scheme"] or deprecated_version_type
         )
+        self.template = arguments["template"] or self.config.settings.get("template")
+        self.extras = arguments["extras"]
 
     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."""
@@ -273,6 +276,8 @@ def __call__(self):  # noqa: C901
                     "unreleased_version": new_tag_version,
                     "incremental": True,
                     "dry_run": dry_run,
+                    "template": self.template,
+                    "extras": self.extras,
                 },
             )
             changelog_cmd()

commitizen/commands/changelog.py

@@ -65,6 +65,9 @@ def __init__(self, config: BaseConfig, args):
             "merge_prerelease"
         ) or self.config.settings.get("changelog_merge_prerelease")
 
+        self.template = args.get("template") or self.config.settings.get("template")
+        self.extras = args.get("extras") or {}
+
     def _find_incremental_rev(self, latest_version: str, tags: list[GitTag]) -> str:
         """Try to find the 'start_rev'.
 
@@ -183,7 +186,13 @@ def __call__(self):
         )
         if self.change_type_order:
             tree = changelog.order_changelog_tree(tree, self.change_type_order)
-        changelog_out = changelog.render_changelog(tree)
+
+        extras = self.cz.template_extras.copy()
+        extras.update(self.config.settings["extras"])
+        extras.update(self.extras)
+        changelog_out = changelog.render_changelog(
+            tree, loader=self.cz.template_loader, template=self.template, **extras
+        )
         changelog_out = changelog_out.lstrip("\n")
 
         if self.dry_run:

commitizen/cz/base.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 from abc import ABCMeta, abstractmethod
-from typing import Callable
+from typing import Any, Callable
 
+from jinja2 import BaseLoader
 from prompt_toolkit.styles import Style, merge_styles
 
 from commitizen import git
+from commitizen.changelog import DEFAULT_TEMPLATE
 from commitizen.config.base_config import BaseConfig
 from commitizen.defaults import Questions
 
@@ -43,6 +45,10 @@ class BaseCommitizen(metaclass=ABCMeta):
     # Executed only at the end of the changelog generation
     changelog_hook: Callable[[str, str | None], str] | None = None
 
+    template: str = DEFAULT_TEMPLATE
+    template_loader: BaseLoader | None = None
+    template_extras: dict[str, Any] = {}
+
     def __init__(self, config: BaseConfig):
         self.config = config
         if not self.config.settings.get("style"):

commitizen/defaults.py

@@ -52,7 +52,8 @@ class Settings(TypedDict, total=False):
     post_bump_hooks: list[str] | None
     prerelease_offset: int
     encoding: str
-    always_signoff: bool
+    template: str | None
+    extras: dict[str, Any]
 
 
 name: str = "cz_conventional_commits"
@@ -94,6 +95,8 @@ class Settings(TypedDict, total=False):
     "prerelease_offset": 0,
     "encoding": encoding,
     "always_signoff": False,
+    "template": None,
+    "extras": {},
 }
 
 MAJOR = "MAJOR"
@@ -125,3 +128,4 @@ class Settings(TypedDict, total=False):
 bump_message = "bump: version $current_version → $new_version"
 
 commit_parser = r"^((?P<change_type>feat|fix|refactor|perf|BREAKING CHANGE)(?:\((?P<scope>[^()\r\n]*)\)|\()?(?P<breaking>!)?|\w+!):\s(?P<message>.*)?"  # noqa
+version_parser = r"(?P<version>([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?(\w+)?)"

docs/bump.md

@@ -58,6 +58,7 @@ usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
                [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
                [--check-consistency] [--annotated-tag] [--gpg-sign]
                [--changelog-to-stdout] [--git-output-to-stderr] [--retry] [--major-version-zero]
+               [--template TEMPLATE] [--extra EXTRA]
                [MANUAL_VERSION]
 
 positional arguments:
@@ -99,6 +100,10 @@ options:
   --version-scheme {pep440,semver}
                         choose version scheme
 
+  --template TEMPLATE, -t TEMPLATE
+                        changelog template file name (relative to the current working directory)
+  --extra EXTRA, -e EXTRA
+                        a changelog extra variable (in the form 'key=value')
 ```
 
 ### `--files-only`
@@ -250,6 +255,21 @@ Can I transition from one to the other?
 
 Yes, you shouldn't have any issues.
 
+### `--template`
+
+Provides your own changelog jinja template.
+See [the template customization section](customization.md#customizing-the-changelog-template)
+
+### `--extra`
+
+Provides your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter.
+
+```bash
+cz bump --changelog --extra key=value -e short="quoted value"
+```
+
+See [the template customization section](customization.md#customizing-the-changelog-template).
+
 ## Avoid raising errors
 
 Some situations from commitizen raise an exit code different than 0.

docs/changelog.md

@@ -14,6 +14,7 @@ update_changelog_on_bump = true
 ```bash
 $ cz changelog --help
 usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME] [--unreleased-version UNRELEASED_VERSION] [--incremental] [--start-rev START_REV]
+                    [--template TEMPLATE] [--extra EXTRA]
                     [rev_range]
 
 positional arguments:
@@ -31,6 +32,11 @@ optional arguments:
                         start rev of the changelog. If not set, it will generate changelog from the start
   --merge-prerelease
                         collect all changes from prereleases into next non-prerelease. If not set, it will include prereleases in the changelog
+                        start rev of the changelog.If not set, it will generate changelog from the start
+  --template TEMPLATE, -t TEMPLATE
+                        changelog template file name (relative to the current working directory)
+  --extra EXTRA, -e EXTRA
+                        a changelog extra variable (in the form 'key=value')
 ```
 
 ### Examples
@@ -186,6 +192,21 @@ cz changelog --merge-prerelease
 changelog_merge_prerelease = true
 ```
 
+### `template`
+
+Provides your own changelog jinja template by using the `template` settings or the `--template` parameter.
+See [the template customization section](customization.md#customizing-the-changelog-template)
+
+### `extras`
+
+Provides your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter.
+
+```bash
+cz changelog --extra key=value -e short="quoted value"
+```
+
+See [the template customization section](customization.md#customizing-the-changelog-template)
+
 ## Hooks
 
 Supported hook methods:

docs/config.md

@@ -166,7 +166,7 @@ Type: `int`
 
 Default: `0`
 
-In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset] |
+In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset]
 
 ### `pre_bump_hooks`
 
@@ -192,6 +192,22 @@ Default: `utf-8`
 
 Sets the character encoding to be used when parsing commit messages. [Read more][encoding]
 
+### `template`
+
+Type: `str`
+
+Default: `None` (provided by plugin)
+
+Provide custom changelog jinja template path relative to the current working directory. [Read more][template-customization]
+
+### `extras`
+
+Type: `dict[str, Any]`
+
+Default: `{}`
+
+Provide extra variables to the changelog template. [Read more][template-customization]
+
 ## Configuration file
 
 ### pyproject.toml or .cz.toml
@@ -364,5 +380,6 @@ setup(
 [additional-features]: https://github.com/tmbo/questionary#additional-features
 [customization]: customization.md
 [shortcuts]: customization.md#shortcut-keys
+[template-customization]: customization.md#customizing-the-changelog-template
 [annotated-tags-vs-lightweight]: https://stackoverflow.com/a/11514139/2047185
 [encoding]: tutorials/writing_commits.md#writing-commits