Generate changelog from Git commits.
- Python 3.6, 3.7, 3.8 and PyPy
Matyan does a good job generating changelog from Git commits. Think of DTAP development, GitFlow-like concepts, JIRA (or similar tool for handling tickets and reviewing pull requests).
If the following applies to you, matyan
could help:
- Project releases (tags) are numbered according to the semantic versioning or sequence based identifiers.
- Project follows the DTAP.
- Testing, acceptance and production branches (hereafter referred as TAP branches) are protected.
- Direct commits to TAP branches are forbidden.
- All commits to TAP branches are made by pull requests.
- Pull requests are merged using GitHub or BitBucket web interface.
- JIRA is used for issues.
- All commits are prefixed with ID of the JIRA issue: for example, MSFT-1234 or NVDA-1234 (where first four letters identify the client commit was done for, it's pattern).
- There are 3 main (protected) branches: dev, staging, master. Direct commits to any of the 3 are forbidden. Any feature/bugfix comes via merge request.
- All branches do have meaningful prefixes. Example, feature/MSFT-1234-Title-of-the-issue or bugfix/MSFT-1236-prevent-duplicate-postal-codes.
- Release flow is dev -> staging -> master.
Consider the following commits into the dev branch:
branch: feature/MSFT-1238-Token-authentication
- MSFT-1238 Implement token authentication.
- MSFT-1238 Update authentication docs.
branch: feature/MSFT-1237-Improve-document-sharing
- MSFT-1237 Improve document sharing. Add option to share via GDrive.
branch: bugfix/MSFT-1236-prevent-duplicate-postal-codes
- MSFT-1236 Normalise postal codes for German addresses.
- MSFT-1236 Normalise postal codes for US addresses.
- MSFT-1236 Make postal code field unique for the country.
branch: deprecation/MSFT-1235-deprecate-old-api
- MSFT-1235 Deprecate API v 2.0.
- MSFT-1235 Update docs.
branch: feature/MSFT-1234-car-type-suggester
- MSFT-1234 Initial car type suggester implementation.
- MSFT-1234 Add insurance amount indication based on car weight.
All commits have been finally merged into master.
Releases have been made in the following way:
0.1
- Merged issues MSFT-1234, MSFT-1235 and MSFT-1236
0.2
- Merged issues MSFT-1237 and MSFT-1238
The generated change log would look as follows:
### 0.2
**Features**
*MSFT-1238 Token-authentication*
- Implement token authentication.
- Update authentication docs.
*MSFT-1237 Improve document sharing*
- Improve document sharing. Add option to share via GDrive.
### 0.1
**Bugfixes**
*MSFT-1236 Prevent duplicate postal codes*
- Normalise postal codes for German addresses.
- Normalise postal codes for US addresses.
- Make postal code field unique for the country.
**Deprecations**
*MSFT-1235 Deprecate old api*
- Deprecate API v 2.0.
- Update docs.
**Features**
*MSFT-1234 Car type suggester*
- Initial car type suggester implementation.
- Add insurance amount indication based on car weight.
In order to customize names and texts, add a .matyan.ini
in your
project directory, form which you will be runnin the generate-changelog
command.
Sample configuration:
[BranchTypes]
feature: Feature
bugfix: Bugfix
hotfix: Hotfix
deprecation: Deprecation
[OtherBranchType]
other: Other
[Unreleased]
unreleased: Unreleased
[IgnoreCommits]
exact: more
clean up
code comments
more on docs
repo
working
more on
wip
commit
generate-changelog --show-releases 2>&1 | tee changelog.md
Documentation is available on Read the Docs.
Latest stable version on PyPI:
pip install matyan
Or latest stable version from GitHub:
pip install https://github.com/barseghyanartur/matyan/archive/stable.tar.gz
Or latest stable version from BitBucket:
pip install https://bitbucket.org/barseghyanartur/matyan/get/stable.tar.gz
Generate changelog:
generate-changelog
Generate changelog skipping orphaned commits:
In some cases you only want to show what has been done with tickets and skip all non-ticket related commits.
generate-changelog --no-other
Generate changelog between two releases:
In some cases you only want to show what has been done since last release. The following example would generate changelog since version 0.0.1 to version 0.0.3.
generate-changelog 0.0.1..0.0.3
Generate changelog with releases info shown
generate-changelog --show-releases
Generate changelog between releases with releases info shown
generate-changelog 0.0.1..0.0.3 --show-releases
Simply type:
./runtests.py
Or use tox:
tox
Or use tox to check specific env:
tox -e py36
Keep the following hierarchy.
=====
title
=====
header
======
sub-header
----------
sub-sub-header
~~~~~~~~~~~~~~
sub-sub-sub-header
^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-header
++++++++++++++++++++++
sub-sub-sub-sub-sub-header
**************************
GPL-2.0-only OR LGPL-2.1-or-later
For any issues contact me at the e-mail given in the Author section.
Artur Barseghyan <artur.barseghyan@gmail.com>
Contents:
.. toctree:: :maxdepth: 20 index changelog matyan