changelog-gen 0.9.1

Changelog generation tool

Changelog Generator - v0.9.1

changelog-gen is a CHANGELOG generator intended to be used in conjunction with bump-my-version to generate changelogs and create release tags.

Migrating to 0.9 (Conventioanl Commit support)

Check the discussion here for details on how to update usage to maintain legacy functionality or move over to new features.

Installation

pip install changelog-gen[bump-my-version]   # recommended

pip install changelog-gen[bump2version]  # bump2version support will be dropped in the future

or clone this repo and install with poetry.

poetry install --extras=bump-my-version

Usage

changelog currently supports generating from commit logs using Conventional Commits, as well as reading changes from a release_notes folder.

NOTE: release_notes support will be dropped in a future version, migration to conventional commits is recommended.

See Configuration below for default commit type configuration and how to customize them.

## <version>

### Features and Improvements
- xxx
- xxx

### Bug fixes
- xxx
- xxx

### Documentation
- xxx
- xxx

### Miscellaneous
- xxx
- xxx

Conventional commits

<type>[(optional scope)][!]: <description>

[optional body]

[optional footer(s)]

description allows typical [a-zA-Z ] sentences, as well as [.,/] punctuation, and [`] for highlighting words.

i.e.

fix: This is a valid description, with punctuation and a `highlighted` word.

Optional footers that are parsed by changelog-gen are:

• BREAKING CHANGE:
• Refs: [#]<issue_ref>
• Authors: (<author>, ...)

The description is used to populate the changelog file. If the type includes the optional ! flag, or the BREAKING CHANGE footer, this will lead to a major release being suggested.

Release Notes

Files in the folder should use the format {issue_number}.{type}.

The contents of each file is used to populate the changelog file. If the type ends with a ! it denotes a breaking change has been made, this will lead to a major release being suggested.

$ ls release_notes
  4.fix  7.fix

$ changelog generate

## v0.2.1

### Bug fixes

- Raise errors from internal classes, don't use click.echo() [#4]
- Update changelog line format to include issue number at the end. [#7]

Write CHANGELOG for suggested version 0.2.1 [y/N]: y

Configuration

Of the command line arguments, most of them can be configured in setup.cfg or pyproject.toml to remove the need to pass them in every time.

Example pyproject.toml:

[tool.changelog_gen]
commit = true
release = true
allow_dirty = false

[tool.changelog_gen.post_process]
  url = "https://your-domain.atlassian.net/rest/api/2/issue/ISSUE-::issue_ref::/comment"
  verb = "POST"
  body = '{"body": "Released on v::version::"}'
  auth_env = "JIRA_AUTH"

NOTE: setup.cfg is being deprecated, use changelog migrate to generate valid toml from existing setup.cfg file.

Example setup.cfg:

[changelog_gen]
commit = true
release = true
allow_dirty = false

Example pyproject.toml:

[tool.changelog_gen]
commit = true
release = true
allow_dirty = false

[tool.changelog_gen.post_process]
  url = "https://your-domain.atlassian.net/rest/api/2/issue/ISSUE-::issue_ref::/comment"
  verb = "POST"
  body = '{"body": "Released on v::version::"}'
  auth_env = "JIRA_AUTH"

Configuration file -- Global configuration

General configuration is grouped in a [changelog_gen] section.

commit = (True | False)

[optional]
default: False

Commit changes to the changelog after writing.

Also available as --commit (e.g. changelog generate --commit)

release = (True | False)

[optional]
default: False

Use bumpversion to tag the release

Also available as --release (e.g. changelog generate --release)

allow_dirty = (True | False)

[optional]
default: False

Don't abort if the current branch contains uncommitted changes

Also available as --allow-dirty (e.g. changelog generate --allow-dirty)

reject_empty = (True | False)

[optional]
default: False

Abort if there are no release notes to add to the change log.

Also available as --reject-empty (e.g. changelog generate --reject-empty)

issue_link =

[optional]
default: None

Create links in the CHANGELOG to the originating issue. A url that contains an issue_ref placeholder for replacement.

Example:

[tool.changelog_gen]
issue_link = "http://github.com/EdgyEdgemond/changelog-gen/issues/::issue_ref::"

commit_link =

[optional]
default: None

Create links in the CHANGELOG to the originating commit. A url that contains a ::commit_hash:: placeholder for replacement.

Example:

[tool.changelog_gen]
commit_link = "http://github.com/EdgyEdgemond/changelog-gen/commit/::commit_hash::"

version_string =

[optional]
default: v{new_version}

Format for the version tag, this will be passed into changelog, commit messages, and any post processing.

Example:

[tool.changelog_gen]
version_string = "{new_version}"

date_format =

[optional]
default: None

Add a date on the version line, use strftime and strptime format codes. The format string can include any character, a space is included between the version tag and the date tag.

When using in setup.cfg be sure to protect the % signs by using %% and be mindful about spacing as the string is taken straight from the = sign.

Also available as --date-format (e.g. --date-format '%Y-%m-%d').

Example:

[tool.changelog_gen]
date_format = "on %Y-%m-%d"

allowed_branches =

[optional]
default: None

Prevent changelog being generated if the current branch is not in the supplied list. By default all branches are allowed.

Example:

[tool.changelog_gen]
allowed_branches = [
  "master",
  "develop",
]

commit_types =

[optional]
default: {
"feat": {
"header": "Features and Improvements",
"semver": "minor", }
"fix": {
"header": "Bug fixes",
"semver": "patch",
},
"docs": {
"header": "Documentation",
"semver": "patch",
},
"bug": {
"header": "Bug fixes",
"semver": "patch",
},
"chore": {
"header": "Miscellaneous",
"semver": "patch",
},
"ci": {
"header": "Miscellaneous",
"semver": "patch",
},
"perf": {
"header": "Miscellaneous",
"semver": "patch",
},
"refactor": {
"header": "Miscellaneous",
"semver": "patch",
},
"revert": {
"header": "Miscellaneous",
"semver": "patch",
},
"style": {
"header": "Miscellaneous",
"semver": "patch",
},
"test": {
"header": "Miscellaneous",
"semver": "patch",
},
}

Define commit types and which headers and semver in the changelog they should map to, default semver is patch.

Example:

[tool.changelog_gen.commit_types]
feat.header = "New Features"
feat.semver = "minor"
change.header = "Changes"
remove.header = "Removals"
remove.semver = "minor"
fix.header = "Bugfixes"

sections =

[Deprecated]
[optional]
default: {
"feat": "Features and Improvements",
"fix": "Bug fixes",
"docs": "Documentation",
"misc": "Miscellaneous",
}

Define custom headers or new sections/headers, new sections will require a matching section_mapping configuration.

This configuration has been deprecated, use commit_types instead.

Example:

[tool.changelog_gen.sections]
feat = "New Features"
change = "Changes"
remove = "Removals"
fix = "Bugfixes"

section_mapping =

[Deprecated]
[optional]
default: {
"bug": "fix",
"chore": "misc",
"ci": "misc",
"docs": "docs",
"perf": "misc",
"refactor": "misc",
"revert": "misc",
"style": "misc",
"test": "misc",
}

Configure additional supported commit types to supported changelog sections.

This configuration has been deprecated, use commit_types instead.

Example:

[tool.changelog_gen.section_mapping]
test = "fix"
bugfix = "fix"
docs = "fix"
new = "feat"

post_process =

[optional]
default: None

Configure a REST API to contact when a release is made

See example on Jira configuration information.

.url =
[required]
default: None
The url to contact. Can have the placeholders ::issue_ref:: and `::version::``.

.verb =
[optional]
default: POST
HTTP method to use.

.body =
[optional]
default: {"body": "Released on ::version::"}
The text to send to the API. Can have the placeholders ::issue_ref:: and ::version::.

.headers =
[optional]
default: None
Headers dictionary to inject into http requests.

If using setup.cfg, provide a json string representation of the headers.

.auth_type =
[optional]
default: basic
Auth type to use for post process requests, supported options are basic and bearer.

.auth_env =
[optional]
default: None
Name of the environment variable to use to extract the basic auth information to contact the API.

• For basic auth the content of the variable should be {user}:{api key}.
• For bearer auth the content of the variable should be {api key}.

Example to post to JIRA:

[tool.changelog_gen.post_process]
url = "https://your-domain.atlassian.net/rest/api/2/issue/ISSUE-::issue_ref::/comment"
verb = "POST"
body = '{"body": "Released on ::version::"}'
auth_env = "JIRA_AUTH"
headers."content-type" = "application/json"

This assumes an environment variable JIRA_AUTH with the content [e-mail]:{api_key}. See manage-api-tokens-for-your-atlassian-account to generate a key.

Also partially available as --post-process-url and --post-process-auth-env (e.g. changelog generate --post-process-url 'http://my-api-url.domain/comment/::issue_ref::' --post-process-auth-env MY_API_AUTH)

Pre-release flows

If your versioning uses prerelease version parts, after a major/minor/patch update creates e.g. v0.0.1rc0, use --version-part=<part> to trigger release flows, based on your configuration.

$ changelog generate --version-part build
... v0.0.1rc1

Contributing

This project uses pre-commit hooks, please run pre-commit install after cloning and installing dev dependencies.