cz-github-jira-conventional

cz-github-jira-conventional 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:

• validate Jira issue IDs when a commit message includes a scope
• create links to GitHub commits in the CHANGELOG.md
• create links to Jira issues in the CHANGELOG.md

The scope is optional both when creating a commit with cz commit and when linting an existing message with cz check. If supplied, it must contain a comma-separated list of Jira issue IDs matching the configured jira_prefix. Each issue ID is rendered as a link to <jira_base_url>/browse/<issue_id> in the changelog.

> cz check --message "fix: correct minor typos in code"
Commit validation: successful!
> cz check --message "fix(XX-42): correct minor typos in code"
Commit validation: successful!
> cz check --message "fix(typos): correct minor typos in code"
commit validation: failed!

When you run cz commit, enter one or more Jira issue IDs at the scope prompt (prefixed or without a prefix, see config below), or press Enter to omit the scope.

> cz commit
? Select the type of change you are committing fix: A bug fix. Correlates with PATCH in SemVer
? JIRA issue number (multiple "42, 123"). XX-
...

The changelog created by cz (cz bump --changelog)will contain links to the commits in Github and the Jira issues.

## v1.0.0 (2021-08-06)

### Features

- **[XX-123](https://myproject.atlassian.net/browse/XX-123)**: create changelogs with links to issues and commits [a374b](https://github.com/apheris/cz-github-jira-conventional/commit/a374b93f39327964f5ab5290252b795647906008)
- **[XX-42](https://myproject.atlassian.net/browse/XX-42),[XX-13](https://myproject.atlassian.net/browse/XX-13)**: allow multiple issue to be referenced in the commit [07ab0](https://github.com/apheris/cz-github-jira-conventional/commit/07ab0e09de36712ab1db93fff0c821ecd80b5849)

Breaking change and migration (next major release)

cz check now rejects free-form scopes such as fix(ui): correct typos, which previous versions accepted. Replace them with Jira issue IDs matching your configuration (for example, fix(XX-42): correct typos), or omit the scope (fix: correct typos). Update commit-message templates and PR titles used for squash merges accordingly.

Required release step: The version bump is deferred to release preparation. Before publishing this change, update both setup.py and .cz.yaml from 3.0.2 to 4.0.0 and include this migration guidance in the changelog/release notes. Do not publish this behavior as a 3.x patch or minor release.

Installation

Install with pip python -m pip install cz-github-jira-conventional

You need to use a cz config file that has the required additional values jira_base_url and github_repo and may contain the optional value jira_prefix.

Example .cz.yaml config for this repository

commitizen:
  name: cz_github_jira_conventional
  tag_format: v$version
  version: 1.0.0
  jira_prefix: XX-
  jira_base_url: https://myproject.atlassian.net
  github_repo: apheris/cz-github-jira-conventional

The jira_prefix can be either

• empty (the user must write the prefix for each issue)
• a string (the prefix will be added automatically)
• a list (for multiple projects, the user will be asked to choose a prefix)

  jira_prefix: 
    - XX-
    - XY-
    - YY-

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
        stages: [commit-msg]
        additional_dependencies: [cz-github-jira-conventional]

Install the hook with

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

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