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

Fixes commitizen-tools#132
Fixes commitizen-tools#384
Fixes commitizen-tools#433
Closes commitizen-tools#376

Author: noirbizarre

commitizen/changelog.py

@@ -31,13 +31,21 @@
 from datetime import date
 from typing import Callable, Dict, Iterable, List, Optional, Tuple
 
-from jinja2 import Environment, PackageLoader
+from jinja2 import (
+    BaseLoader,
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+)
 
 from commitizen import defaults
 from commitizen.bump import normalize_tag
 from commitizen.exceptions import InvalidConfigurationError, NoCommitsFoundError
 from commitizen.git import GitCommit, GitTag
 
+DEFAULT_TEMPLATE = "keep_a_changelog_template.j2"
+
 
 def get_commit_tag(commit: GitCommit, tags: List[GitTag]) -> Optional[GitTag]:
     return next((tag for tag in tags if tag.rev == commit.rev), None)
@@ -139,11 +147,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: Optional[BaseLoader] = None,
+    template: Optional[str] = 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

@@ -1,6 +1,7 @@
 import argparse
 import logging
 import sys
+from copy import deepcopy
 from functools import partial
 from types import TracebackType
 from typing import List
@@ -17,6 +18,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": (
@@ -190,6 +236,7 @@
                         "default": None,
                         "help": "keep major version at zero, even for breaking changes",
                     },
+                    *deepcopy(tpl_arguments),
                     {
                         "name": ["--prerelease-offset"],
                         "type": int,
@@ -252,6 +299,7 @@
                             "If not set, it will generate changelog from the start"
                         ),
                     },
+                    *deepcopy(tpl_arguments),
                 ],
             },
             {

commitizen/commands/bump.py

@@ -48,6 +48,7 @@ def __init__(self, config: BaseConfig, arguments: dict):
                     "annotated_tag",
                     "major_version_zero",
                     "prerelease_offset",
+                    "template",
                 ]
                 if arguments[key] is not None
             },
@@ -62,6 +63,8 @@ def __init__(self, config: BaseConfig, arguments: dict):
         self.retry = arguments["retry"]
         self.pre_bump_hooks = self.config.settings["pre_bump_hooks"]
         self.post_bump_hooks = self.config.settings["post_bump_hooks"]
+        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."""
@@ -255,6 +258,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

@@ -49,6 +49,8 @@ def __init__(self, config: BaseConfig, args):
         self.tag_format = args.get("tag_format") or self.config.settings.get(
             "tag_format"
         )
+        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'.
@@ -161,7 +163,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,9 +1,13 @@
+from __future__ import annotations
+
 from abc import ABCMeta, abstractmethod
-from typing import Callable, Dict, List, Optional, Tuple
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
+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
 
@@ -40,6 +44,10 @@ class BaseCommitizen(metaclass=ABCMeta):
     # Executed only at the end of the changelog generation
     changelog_hook: Optional[Callable[[str, Optional[str]], str]] = None
 
+    template: str = DEFAULT_TEMPLATE
+    template_loader: Optional[BaseLoader] = None
+    template_extras: dict[str, Any] = {}
+
     def __init__(self, config: BaseConfig):
         self.config = config
         if not self.config.settings.get("style"):

commitizen/defaults.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pathlib
 from collections import OrderedDict
 from typing import Any, Dict, Iterable, List, MutableMapping, Optional, Tuple, Union
@@ -44,6 +46,8 @@ class Settings(TypedDict, total=False):
     pre_bump_hooks: Optional[List[str]]
     post_bump_hooks: Optional[List[str]]
     prerelease_offset: int
+    template: Optional[str]
+    extras: dict[str, Any]
 
 
 name: str = "cz_conventional_commits"
@@ -73,6 +77,8 @@ class Settings(TypedDict, total=False):
     "pre_bump_hooks": [],
     "post_bump_hooks": [],
     "prerelease_offset": 0,
+    "template": None,
+    "extras": {},
 }
 
 MAJOR = "MAJOR"

docs/bump.md

@@ -60,6 +60,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] [--retry] [--major-version-zero]
+               [--template TEMPLATE] [--extra EXTRA]
                [MANUAL_VERSION]
 
 positional arguments:
@@ -96,6 +97,10 @@ options:
   --retry               retry commit if it fails the 1st time
   --major-version-zero  keep major version at zero, even for breaking changes
   --prerelease-offset   start pre-releases with this offset
+  --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`
@@ -214,6 +219,21 @@ We recommend setting `major_version_zero = true` in your configuration file whil
 is in its initial development. Remove that configuration using a breaking-change commit to bump
 your project’s major version to `v1.0.0` once your project has reached maturity.
 
+### `--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 rise an exit code different than 0.

docs/changelog.md

@@ -7,6 +7,7 @@ This command will generate a changelog following the committing rules establishe
 ```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:
@@ -22,6 +23,10 @@ optional arguments:
   --incremental         generates changelog from last created version, useful if the changelog has been manually modified
   --start-rev START_REV
                         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
@@ -161,6 +166,21 @@ cz changelog --start-rev="v0.2.0"
 changelog_start_rev = "v0.2.0"
 ```
 
+### `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

@@ -22,6 +22,8 @@
 | `use_shortcuts`            | `bool` | `false`                     | If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [See more][shortcuts]                                                                                        |
 | `major_version_zero`       | `bool` | `false`                     | When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [major-version-zero]                                                                                        |
 | `prerelease_offset`        | `int`  | `0`                         | In special cases it may be necessary that a prerelease cannot start with a 0, e.g. in an embedded project the individual characters are encoded in bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset] |
+| <a name="cfg-template"></a>`template` | `str`  | `None`  | Provide custom changelog jinja template path relative to the current working directory. [See more (template customization)][template-customization] |
+| <a name="cfg-extras"></a>`extras` | `dict`  | `{}`  | Provide extra variables to the changelog template. [See more (template customization)][template-customization] |
 
 ## pyproject.toml or .cz.toml
 
@@ -181,4 +183,5 @@ 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

docs/customization.md

@@ -435,3 +435,84 @@ setup(
 ```
 
 Then your plugin will be available under the name `plugin`.
+
+## Customizing the changelog template
+
+Commitizen gives you the possibility to provide your own changelog template, by:
+
+- providing one with your customization class
+- providing one from the current working directory and setting it:
+    - as [configuration][template-config]
+    - as `--template` parameter to both `bump` and `changelog` commands
+- either by providing a template with the same name as the default template
+
+By default, the template used is the `keep_a_changelog_template.j2` file from the commitizen repository.
+
+### Providing a template with your customization class
+
+There is 3 parameters available to hcange the template rendering from your custom `BaseCommitizen`.
+
+| Parameter         | Type   | Default | Description                                                                                           |
+| ----------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
+| `template`        | `str`  | `None`  | Provide your own template name (default to `keep_a_changelog_template.j2`)                            |
+| `template_loader` | `str`  | `None`  | Override the default template loader (so you can provide template from you customization class)       |
+| `template_extras` | `dict` | `None`  | Provide some extra template parameters                                                                |
+
+Let's see an example.
+
+```python
+from commitizen.cz.base import BaseCommitizen
+from jinja2 import PackageLoader
+
+
+class MyPlugin(BaseCommitizen):
+    template = "CHANGELOG.md.jinja"
+    template_loader = PackageLoader("my_plugin", "templates")
+    template_extras = {"key": "value"}
+```
+
+This snippet will:
+
+- use `CHANGELOG.md.jinja` as template name
+- search for it in the `templates` directory for `my_plugin` package
+- add the `key=value` variable in the template
+
+### Providing a template from the current working directory
+
+Users can provides their own template from their current working directory (your project root) by:
+
+- providing a template with the same name (`keep_a_changelog_template.j2` unless overriden by your custom class)
+- setting your template path as `template` configuration
+- giving your template path as `--template` parameter to `bump` and `changelog` commands
+
+!!! Note
+    The path is relative to the current working directory, aka. your project root most of the time,
+
+### Template variables
+
+The default template use a single `tree` variable which is a list of entries (a release) with the following format:
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| version | `str` | The release version |
+| date | `datetime` | The release date |
+| changes | `list[tuple[str, list[Change]]]` | The release sorted changes list in the form `(type,changes)` |
+
+Each `Change` has the following fields:
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| scope | `Optional[str]` | An optionnal scope |
+| message | `str` | The commit message body |
+
+!!! Note
+    The field values depend on the customization class and/or the settings you provide
+
+When using another template (either provided by a plugin or by yourself), you can also pass extra template variables
+by:
+
+- defining them in your configuration with the [`extras` settings][extras-config]
+- providing them on the commandline with the `--extra/-e` parameter to `bump` and `changelog` commands
+
+[template-config]: config.md#cfg-template
+[extras-config]: config.md#cfg-extras

tests/commands/test_bump_command.py

@@ -1,5 +1,7 @@
 import inspect
 import sys
+from pathlib import Path
+from textwrap import dedent
 from typing import Tuple
 from unittest.mock import MagicMock, call
 
@@ -8,6 +10,8 @@
 
 import commitizen.commands.bump as bump
 from commitizen import cli, cmd, git, hooks
+from commitizen.changelog import DEFAULT_TEMPLATE
+from commitizen.cz.base import BaseCommitizen
 from commitizen.exceptions import (
     BumpTagFailedError,
     CommitizenException,
@@ -853,3 +857,129 @@ def test_bump_use_version_provider(mocker: MockFixture):
     get_provider.assert_called_once()
     mock.get_version.assert_called_once()
     mock.set_version.assert_called_once_with("0.0.1")
+
+
+@pytest.mark.parametrize(
+    "arg,cfg,expected",
+    (
+        pytest.param("", "", "default", id="default"),
+        pytest.param("", "changelog.cfg", "from config", id="from-config"),
+        pytest.param(
+            "--template=changelog.cmd", "changelog.cfg", "from cmd", id="from-command"
+        ),
+    ),
+)
+def test_bump_template_option_precedance(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+    mock_plugin: BaseCommitizen,
+    arg: str,
+    cfg: str,
+    expected: str,
+):
+    project_root = Path(tmp_commitizen_project)
+    cfg_template = project_root / "changelog.cfg"
+    cmd_template = project_root / "changelog.cmd"
+    default_template = project_root / mock_plugin.template
+    changelog = project_root / "CHANGELOG.md"
+
+    cfg_template.write_text("from config")
+    cmd_template.write_text("from cmd")
+    default_template.write_text("default")
+
+    create_file_and_commit("feat: new file")
+
+    if cfg:
+        pyproject = project_root / "pyproject.toml"
+        pyproject.write_text(
+            dedent(
+                f"""\
+                [tool.commitizen]
+                version = "0.1.0"
+                template = "{cfg}"
+                """
+            )
+        )
+
+    testargs = ["cz", "bump", "--yes", "--changelog"]
+    if arg:
+        testargs.append(arg)
+    mocker.patch.object(sys, "argv", testargs + ["0.1.1"])
+    cli.main()
+
+    out = changelog.read_text()
+    assert out == expected
+
+
+def test_bump_template_extras_precedance(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+    mock_plugin: BaseCommitizen,
+):
+    project_root = Path(tmp_commitizen_project)
+    changelog_tpl = project_root / DEFAULT_TEMPLATE
+    changelog_tpl.write_text("{{first}} - {{second}} - {{third}}")
+
+    mock_plugin.template_extras = dict(
+        first="from-plugin", second="from-plugin", third="from-plugin"
+    )
+
+    pyproject = project_root / "pyproject.toml"
+    pyproject.write_text(
+        dedent(
+            """\
+            [tool.commitizen]
+            version = "0.1.0"
+
+            [tool.commitizen.extras]
+            first = "from-config"
+            second = "from-config"
+            """
+        )
+    )
+
+    create_file_and_commit("feat: new file")
+
+    testargs = [
+        "cz",
+        "bump",
+        "--yes",
+        "--changelog",
+        "--extra",
+        "first=from-command",
+        "0.1.1",
+    ]
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    changelog = project_root / "CHANGELOG.md"
+    assert changelog.read_text() == "from-command - from-config - from-plugin"
+
+
+def test_bump_template_extra_quotes(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+):
+    project_root = Path(tmp_commitizen_project)
+    changelog_tpl = project_root / DEFAULT_TEMPLATE
+    changelog_tpl.write_text("{{first}} - {{second}} - {{third}}")
+
+    create_file_and_commit("feat: new file")
+
+    testargs = [
+        "cz",
+        "bump",
+        "--changelog",
+        "--yes",
+        "-e",
+        "first=no-quote",
+        "-e",
+        "second='single quotes'",
+        "-e",
+        'third="double quotes"',
+    ]
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    changelog = project_root / "CHANGELOG.md"
+    assert changelog.read_text() == "no-quote - single quotes - double quotes"

tests/commands/test_changelog_command.py

@@ -1,11 +1,15 @@
 import sys
 from datetime import datetime
+from pathlib import Path
+from textwrap import dedent
 
 import pytest
 from pytest_mock import MockFixture
 
 from commitizen import cli, git
+from commitizen.changelog import DEFAULT_TEMPLATE
 from commitizen.commands.changelog import Changelog
+from commitizen.cz.base import BaseCommitizen
 from commitizen.exceptions import (
     DryRunExit,
     NoCommitsFoundError,
@@ -969,3 +973,119 @@ def test_empty_commit_list(mocker):
     mocker.patch.object(sys, "argv", testargs)
     with pytest.raises(NoCommitsFoundError):
         cli.main()
+
+
+@pytest.mark.parametrize(
+    "arg,cfg,expected",
+    (
+        pytest.param("", "", "default", id="default"),
+        pytest.param("", "changelog.cfg", "from config", id="from-config"),
+        pytest.param(
+            "--template=changelog.cmd", "changelog.cfg", "from cmd", id="from-command"
+        ),
+    ),
+)
+def test_changelog_template_option_precedance(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+    mock_plugin: BaseCommitizen,
+    arg: str,
+    cfg: str,
+    expected: str,
+):
+    project_root = Path(tmp_commitizen_project)
+    cfg_template = project_root / "changelog.cfg"
+    cmd_template = project_root / "changelog.cmd"
+    default_template = project_root / mock_plugin.template
+    changelog = project_root / "CHANGELOG.md"
+
+    cfg_template.write_text("from config")
+    cmd_template.write_text("from cmd")
+    default_template.write_text("default")
+
+    create_file_and_commit("feat: new file")
+
+    if cfg:
+        pyproject = project_root / "pyproject.toml"
+        pyproject.write_text(
+            dedent(
+                f"""\
+                [tool.commitizen]
+                version = "0.1.0"
+                template = "{cfg}"
+                """
+            )
+        )
+
+    testargs = ["cz", "changelog"]
+    if arg:
+        testargs.append(arg)
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    out = changelog.read_text()
+    assert out == expected
+
+
+def test_changelog_template_extras_precedance(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+    mock_plugin: BaseCommitizen,
+):
+    project_root = Path(tmp_commitizen_project)
+    changelog_tpl = project_root / mock_plugin.template
+    changelog_tpl.write_text("{{first}} - {{second}} - {{third}}")
+
+    mock_plugin.template_extras = dict(
+        first="from-plugin", second="from-plugin", third="from-plugin"
+    )
+
+    pyproject = project_root / "pyproject.toml"
+    pyproject.write_text(
+        dedent(
+            """\
+            [tool.commitizen]
+            version = "0.1.0"
+
+            [tool.commitizen.extras]
+            first = "from-config"
+            second = "from-config"
+            """
+        )
+    )
+
+    create_file_and_commit("feat: new file")
+
+    testargs = ["cz", "changelog", "--extra", "first=from-command"]
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    changelog = project_root / "CHANGELOG.md"
+    assert changelog.read_text() == "from-command - from-config - from-plugin"
+
+
+def test_changelog_template_extra_quotes(
+    mocker: MockFixture,
+    tmp_commitizen_project: Path,
+):
+    project_root = Path(tmp_commitizen_project)
+    changelog_tpl = project_root / DEFAULT_TEMPLATE
+    changelog_tpl.write_text("{{first}} - {{second}} - {{third}}")
+
+    create_file_and_commit("feat: new file")
+
+    testargs = [
+        "cz",
+        "changelog",
+        "-e",
+        "first=no-quote",
+        "-e",
+        "second='single quotes'",
+        "-e",
+        'third="double quotes"',
+    ]
+    mocker.patch.object(sys, "argv", testargs)
+    cli.main()
+
+    changelog = project_root / "CHANGELOG.md"
+    assert changelog.read_text() == "no-quote - single quotes - double quotes"

tests/conftest.py

@@ -2,11 +2,14 @@
 import re
 import tempfile
 from pathlib import Path
+from typing import Iterator
 
 import pytest
+from pytest_mock import MockerFixture
 
 from commitizen import cmd, defaults
 from commitizen.config import BaseConfig
+from commitizen.cz.base import BaseCommitizen
 
 SIGNER = "GitHub Action"
 SIGNER_MAIL = "action@github.com"
@@ -26,6 +29,14 @@ def git_sandbox(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
     cmd.run(f"git config --global user.email {SIGNER_MAIL}")
 
 
+@pytest.fixture
+def chdir(tmp_path: Path) -> Iterator[Path]:
+    cwd = os.getcwd()
+    os.chdir(tmp_path)
+    yield tmp_path
+    os.chdir(cwd)
+
+
 @pytest.fixture(scope="function")
 def tmp_git_project(tmpdir):
     with tmpdir.as_cwd():
@@ -85,3 +96,18 @@ def config():
 @pytest.fixture()
 def config_path() -> str:
     return os.path.join(os.getcwd(), "pyproject.toml")
+
+
+class MockPlugin(BaseCommitizen):
+    def questions(self) -> defaults.Questions:
+        return []
+
+    def message(self, answers: dict) -> str:
+        return ""
+
+
+@pytest.fixture
+def mock_plugin(mocker: MockerFixture, config: BaseConfig) -> BaseCommitizen:
+    mock = MockPlugin(config)
+    mocker.patch("commitizen.factory.commiter_factory", return_value=mock)
+    return mock

tests/test_changelog.py

@@ -1,4 +1,7 @@
+from pathlib import Path
+
 import pytest
+from jinja2 import FileSystemLoader
 
 from commitizen import changelog, defaults, git
 from commitizen.cz.conventional_commits.conventional_commits import (
@@ -853,6 +856,91 @@ def test_render_changelog(gitcommits, tags, changelog_content):
     assert result == changelog_content
 
 
+def test_render_changelog_from_default_plugin_values(
+    gitcommits, tags, changelog_content
+):
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    loader = ConventionalCommitsCz.template_loader
+    template = ConventionalCommitsCz.template
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(tree, loader=loader, template=template)
+    assert result == changelog_content
+
+
+def test_render_changelog_override_loader(gitcommits, tags, tmp_path: Path):
+    loader = FileSystemLoader(tmp_path)
+    tpl = "loader overridden"
+    (tmp_path / changelog.DEFAULT_TEMPLATE).write_text(tpl)
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(tree, loader=loader)
+    assert result == tpl
+
+
+def test_render_changelog_override_template_from_cwd(gitcommits, tags, chdir: Path):
+    tpl = "overridden from cwd"
+    (chdir / changelog.DEFAULT_TEMPLATE).write_text(tpl)
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(tree)
+    assert result == tpl
+
+
+def test_render_changelog_override_template_from_cwd_with_custom_name(
+    gitcommits, tags, chdir: Path
+):
+    tpl = "template overridden from cwd"
+    tpl_name = "tpl.j2"
+    (chdir / tpl_name).write_text(tpl)
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(tree, template=tpl_name)
+    assert result == tpl
+
+
+def test_render_changelog_override_loader_and_template(
+    gitcommits, tags, tmp_path: Path
+):
+    loader = FileSystemLoader(tmp_path)
+    tpl = "loader and template overridden"
+    tpl_name = "tpl.j2"
+    (tmp_path / tpl_name).write_text(tpl)
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(tree, loader=loader, template=tpl_name)
+    assert result == tpl
+
+
+def test_render_changelog_support_arbitrary_kwargs(gitcommits, tags, tmp_path: Path):
+    loader = FileSystemLoader(tmp_path)
+    tpl_name = "tpl.j2"
+    (tmp_path / tpl_name).write_text("{{ key }}")
+    parser = ConventionalCommitsCz.commit_parser
+    changelog_pattern = ConventionalCommitsCz.bump_pattern
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(
+        tree, loader=loader, template=tpl_name, key="value"
+    )
+    assert result == "value"
+
+
 def test_render_changelog_unreleased(gitcommits):
     some_commits = gitcommits[:7]
     parser = ConventionalCommitsCz.commit_parser

tests/test_conf.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import json
 import os
 from pathlib import Path
+from typing import Any
 
 import pytest
 import yaml
@@ -41,7 +44,7 @@
 }
 
 
-_settings = {
+_settings: dict[str, Any] = {
     "name": "cz_jira",
     "version": "1.0.0",
     "version_provider": "commitizen",
@@ -59,9 +62,11 @@
     "pre_bump_hooks": ["scripts/generate_documentation.sh"],
     "post_bump_hooks": ["scripts/slack_notification.sh"],
     "prerelease_offset": 0,
+    "template": None,
+    "extras": {},
 }
 
-_new_settings = {
+_new_settings: dict[str, Any] = {
     "name": "cz_jira",
     "version": "2.0.0",
     "version_provider": "commitizen",
@@ -79,6 +84,8 @@
     "pre_bump_hooks": ["scripts/generate_documentation.sh"],
     "post_bump_hooks": ["scripts/slack_notification.sh"],
     "prerelease_offset": 0,
+    "template": None,
+    "extras": {},
 }
 
 _read_settings = {