Changelog generation tool
Project description
Changelog Generator - v0.9.0
changelog-gen
is a CHANGELOG generator intended to be used in conjunction
with bump-my-version to generate
changelogs and create release tags.
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 user@domain.com:{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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for changelog_gen-0.9.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c5b5717db7ef126b5cf60f0e7ead5d0c6c13d02b00011bf786142335fdcf624c |
|
MD5 | 0c06e0a446235bfa6e74b2fe971b7e2c |
|
BLAKE2b-256 | 2ec305a5a4181c97e626cb0fcc0def2cbfc6794df32ebbb0709a52043ed5dfed |