Metadata-Version: 2.4
Name: cz_github_jira_conventional
Version: 4.0.0
Summary: Extend the commitizen tools to create conventional commits and README that link to Jira and GitHub.
Home-page: https://github.com/apheris/cz-github-jira-conventional
Author: Falko Krause, apheris AI GmbH
Author-email: f.krause@apheris.com
License: MIT
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: commitizen>=4.7.2
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# cz-github-jira-conventional

**cz-github-jira-conventional** is a plugin for the [**commitizen tools**](https://github.com/commitizen-tools/commitizen), a toolset that helps you to create [**conventional commit messages**](https://www.conventionalcommits.org/en/v1.0.0/). Since the structure of conventional commits messages is standardized they are machine readable and allow commitizen to automaticially calculate and tag [**semantic version numbers**](https://semver.org/) 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.
```markdown
## 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
```yaml
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)

```yaml
  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.
```yaml
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 
```bash
pre-commit install --hook-type commit-msg
```

<!-- LICENSE -->
## License

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

<!-- ACKNOWLEDGEMENTS -->
## Acknowledgements
This plugin would not have been possible without the fantastic work from:
* [commitizen tools](https://github.com/commitizen-tools/commitizen)
* [conventional_JIRA](https://github.com/Crystalix007/conventional_jira)
