Matyan¶
Generate changelog from Git commits.
Prerequisites¶
- Python 3.6, 3.7 and 3.8
Documentation¶
Documentation is available on Read the Docs.
Usage¶
See Basic concepts section to get impression on possible commit methodology and assumptions taken.
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 between two branches:
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 master..dev
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
Generate changelog between branches with releases info shown
generate-changelog master..dev --show-releases
Generate changelog for the latest release with releases info shown
generate-changelog --latest-release --show-releases
Configuration¶
In order to customize names and texts, add a .matyan.ini
in your
project directory, form which you will be running 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
prefix: more on
continue on
Tips and tricks¶
Write to file¶
generate-changelog --show-releases 2>&1 | tee changelog.md
Create initial config file¶
matyan-create-config
Writing documentation¶
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
**************************
License¶
GPL-2.0-only OR LGPL-2.1-or-later
Author¶
Artur Barseghyan <artur.barseghyan@gmail.com>
Docs¶
Contents:
Use cases and basic concepts¶
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.
- JIRA (or a similar tool) is used for handing project tickets.
- Pull requests are merged using GitHub or BitBucket web interface.
Sample use-case¶
The use-case¶
- 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.
Sample commits¶
Consider the following commits into the dev branch:
branch: bugfix/MSFT-1240-LinkedIn-authentication-failing
- MSFT-1240 Fix package configuration.
- MSFT-1240 Update authentication pipeline.
branch: deprecation/MSFT-1239-Deprecate-Python2
- MSFT-1239 Deprecate Python2.
- MSFT-1238 Add initial MyPY setup.
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.
Sample releases¶
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
Yet unreleased features/branches
- MSFT-1239 and
Sample changelog output¶
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.
Methodology¶
- Protect your main (DTAP) branches from direct commits. Commits shall only arrive into these branches via pull request.
- Use feature branches. Make your own prefixes (or use current ones) for classification of the ticket. Add ticket name to the name of the branch, followed by slugified ticket title.
- Prefix commits with ticket number followed by meaningful description.
Sample branch names:
bugfix/MSFT-1240-LinkedIn-authentication-failing
deprecation/MSFT-1239-Deprecate-Python2
feature/MSFT-1238-Token-authentication
Sample commit messages:
MSFT-1240 Fix package configuration.
MSFT-1239 Deprecate Python2.
MSFT-1238 Implement token authentication.
Release history and notes¶
Sequence based identifiers are used for versioning (schema follows below):
major.minor[.revision]
- It’s always safe to upgrade within the same minor version (for example, from 0.3 to 0.3.4).
- Minor version changes might be backwards incompatible. Read the release notes carefully before upgrading (for example, when upgrading from 0.3.4 to 0.4).
- All backwards incompatible changes are mentioned in this document.
0.2¶
2019-11-19
- Hide empty sections/records.
- Add an option to generate changelog for latest release only.
- Handle multiple merge format commit messages.
- Prevent JSON decoding errors.
- Exclude tests from coverage.
0.1¶
2019-11-18
Note
Release dedicated to my mother, who turned 70 yesterday.
- Status changed to beta.
- Minor fixes.
- Add matyan-create-config command.
- Add initial tests.