~~Link commits in changelog~~ add `plugin_path` option to enable loading local plugins

[jtpavlock]

Description

Add the ability to link a changelog message to the original commit. This would greatly increase the ability to provide context around changes.

Possible Solution

~~Ability to add a changelog option, so when generating a changelog, it would just add links in the generated markdown for the associated commit message.~~

After https://github.com/commitizen-tools/commitizen/issues/396#issuecomment-878673634, we decide adding a plugin_path might be a good solution for it.

[woile]

Hello! This can be achieved using a custom hook. https://commitizen-tools.github.io/commitizen/customization.html#custom-changelog-generator You can use changelog_message_builder_hook

In the example you can see the commit author is being added to each commit, the same can be done for commits:

def changelog_message_builder_hook(self, parsed_message: dict, commit: git.GitCommit) -> dict:
        rev = commit.rev
        m = parsed_message["message"]
        parsed_message["message"] = f"{m} {rev} [{commit.rev}](github.com/project/{commit.rev})"
        return parsed_message

I don't think it makes sense to add links, because if we add github link any other git server (gitlab, bitbucket, etc) would have to have something similar.

[jtpavlock]

Thanks for the response! Although I think I'm a bit confused how I would add the above function you mentioned to a python configuration file alongside my project. The docs seem to imply I need an entirely separate package/github repo? That seems a bit excessive for a small project-specific configuration change.

[Lee-W]

Yes, I think that's the only way as of now.

[woile]

As of now the changelog provides some flexibility. Extra functionality like sending slack messages, customizing what is shown in the changelog, like emojis, github links, etc are considered out of the scope of the flexibility we can provide. You could create a new custom changelog with the github commits and list it in the third party section, we have a template (which needs some love :/)

I think the design could be improved, but we don't have the capacity at the moment, sorry for that.

[jtpavlock]

Could adding a config setting pointing to a python file work?

The following code is a snippet that can be used to import a module from a given plugin_path filename

plugin_spec = importlib.util.spec_from_file_location(plugin_path.stem, plugin_path)
    if plugin_spec:
        plugin_module = importlib.util.module_from_spec(plugin_spec)
        plugin_spec.loader.exec_module(plugin_module)

source: https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly

Maybe then plugin_module could be added to the list of plugins that you import normally?

[Lee-W]

Does that mean we'll need to add a plugin_path configuration?

This is how we load cz_ as of now https://github.com/commitizen-tools/commitizen/blob/master/commitizen/cz/init.py

[jtpavlock]

Does that mean we'll need to add a plugin_path configuration?

Yes, that's correct.

[Lee-W]

Then I think this issue also relates to https://github.com/commitizen-tools/commitizen/issues/264#issuecomment-877240010. We'll need to make cz configurable first. It's on our plan but we're quite busy these days. Not sure when could we support this feature

[jtpavlock]

I think I'm a bit confused. I'm talking about having a configuration option in your pyproject.toml called plugin_path that would point to a local plugin file so users could easily implement their own project-specific plugins without having to create a whole new package on PYPI.

[Lee-W]

After a second thought, I was wrong about the idea. Yep, I think we could add this option. @Woile What do you think?

[jtpavlock]

@Lee-W could you point me towards the relevant code/steps needed to add a new configuration option? If you guys are keen on adding this as a feature, that is.

[Lee-W]

commitizen/config/init.py is the file that we use to manage the configuration. But I think we might not need to change it, unless the configuration is complicated.

commitizen/cz/init.py is where we load these cz rules. I think this one might be more relevant.

[usrme]

Example on how to add a custom Python module: https://github.com/commitizen-tools/commitizen/issues/395#issuecomment-894586766.