cz-github-jira-conventional-footer 1.0.2

Extend the commitizen tools to create conventional commits and changelog that link to Jira and GitHub.

cz-github-jira-conventional-footer

cz-github-jira-conventional-footer is a plugin for the commitizen tools, a toolset that helps you to create conventional commit messages. Since the structure of conventional commits messages is standardized they are machine readable and allow commitizen to automaticially calculate and tag semantic version numbers as well as create CHANGELOG.md files for your releases.

This plugin extends the commitizen tools by:

• adding Jira issue identifiers in a customisable footer of the commit message
• creating links to GitHub commits in the CHANGELOG.md
• creating links to Jira issues in the CHANGELOG.md

Installation

Install with pip

python -m pip install cz-github-jira-conventional-footer

Configuration

The behavior of the plugin can be modified by adding the following values to your .yaml/.toml/.json config file. Note that github_repo and jira_base_url are required while the others are optional.

Parameter	Type	Required	Default	Description
github_repo	str	YES		Name of the repository on GitHub in format "{username}/{repo name}"
jira_base_url	str	YES		Base URL of the Jira application that tracks issues for this repository
jira_prefix	str	NO	None	Key for the Jira project that tracks issues for this repository. If issues for this repository are tracked on multiple Jira projects, this config value should be left blank which will prompt commitizen for full issue identifiers
jira_token	str	NO	Jira	Token to use for the footer containing Jira issues. Cannot contain spaces or the phrase "Breaking Change". Can optionally specify the separator as either :<space>[^yaml-note] or <space># by including it in the value. If the separator is not specified, a :<space> separator will automatically be added
bump_pattern	str	NO	commitizen.defaults.bump_pattern	Regex to extract information from commit (subject and body)
bump_map	dict	NO	commitizen.defaults.bump_map	Dictionary mapping the extracted information to a SemVer increment type (MAJOR, MINOR, PATCH)
changelog_pattern	str	NO	bump_pattern	Regex to validate the commits, this is useful to skip commits that don't meet your ruling standards like a Merge. Usually the same as bump_pattern
change_type_map	dict	NO	{"feat":"Features", "fix":"Bug Fixes", "refactor":"Refactor", "perf":"Performance Improvements"}	Convert the title of the change type that will appear in the changelog, if a value is not found, the original will be used

[^yaml-note]: The colon (:) character has a special meaning in YAML syntax and must be escaped by enclosing the entire value in single quotes (ex: jira_token: 'resolves-issue: ')

pre-commit

Add this plugin to the dependencies of your commit message linting with pre-commit.

Example .pre-commit-config.yaml file:

repos:
  - repo: https://github.com/commitizen-tools/commitizen
    rev: v2.17.13
    hooks:
      - id: commitizen
        additional_dependencies: [cz-github-jira-conventional-footer]

Install the hook with

pre-commit install --hook-type commit-msg

Example Usage

Configuration

Example .cz.yaml file:

commitizen:
  name: cz_github_jira_conventional_footer
  tag_format: v$version
  version: 0.3.1
  github_repo: brianburwell11/cz-github-jira-conventional-footer
  jira_base_url: https://myproject.atlassian.net
  jira_prefix: XX-

Making a Commit

When you call commitizen commit you will be prompted to enter the scope of your commit as a Jira issue id (or multiple issue ids, prefixed or without prefix, see config above).

$ cz commit
? Select the type of change you are committing feat: A new feature. Correlates with MINOR in SemVer
? What is the scope of this change? (class or file name): (press [enter] to skip)
 changelog
? Write a short and imperative summary of the code changes: (lower case and no period)
 add GitHub and Jira badges to CHANGELOG
? Provide additional contextual information about the code changes: (press [enter] to skip)
 Modify `changelog_message_builder_hook()` to show the commit hash and Jira issues as badges in each entry of the changelog. This is enabled by named groups in the `commit_parser` regex pattern.
? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No
? JIRA issue number (multiple "42, 123"). XX- 03, 04
? Add any additional footers. (press [enter] to skip)
 added-by: Brian Burwell <[e-mail]>

Creates the following commit message:

feat(changelog): add GitHub and Jira badges to CHANGELOG

Modify `changelog_message_builder_hook()` to show the commit hash and Jira issues as badges in each entry of the changelog. This is enabled by named groups in the `commit_parser` regex pattern.

Jira: XX-03,XX-04
added-by: Brian Burwell <[e-mail]>

Reading the Changelog

The changelog created by commitizen (cz changelog or cz bump --changelog) contains links to the commits in Github and the Jira issues.

### Features

- [![b56ea](https://img.shields.io/badge/-b56ea-%23121011.svg?style=flat-square&logo=github&logoColor=white)](https://github.com/brianburwell11/cz-github-jira-conventional-footer/commit/b56ea677af8a969614b159316d9d28a3267f7169)[![XX-03](https://img.shields.io/badge/-XX--03-dfe1e5.svg?style=flat-square&logo=jira&logoColor=0052cc)](https://myproject.atlassian.net/browse/XX-03)[![XX-04](https://img.shields.io/badge/-XX--04-dfe1e5.svg?style=flat-square&logo=jira&logoColor=0052cc)](https://myproject.atlassian.net/browse/XX-04) _(changelog)_ add GitHub and Jira badges to CHANGELOG

which renders as

Features

• (changelog) add GitHub and Jira badges to CHANGELOG

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgements

This plugin would not have been possible without the fantastic work from:

• commitizen tools
• conventional_JIRA
• cz_github_jira_conventional