Matyan¶
Generate changelog from Git commits.
Prerequisites¶
- Python 3.6, 3.7 and 3.8
Documentation¶
Documentation is available on Read the Docs.
Usage¶
Basic 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 would 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 other cases you would 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:
Sometimes you just need to show the changes made on acceptance since last production release. The following example would generate changelog with changes that are on acceptance branch and not yet in master.
generate-changelog master..acceptance
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
Generate changelog with headings only (no commit messages) and releases info shown
generate-changelog --headings-only --show-releases
Generate changelog between two branches, show unreleased changes only:
generate-changelog master..acceptance --show-releases --unreleased-only
Rendering¶
The following renderers are implemented:
- Markdown
- RestructuredText
- Historical Markdown (for compatibility with
matyan
versions prior to 0.4).
Markdown¶
generate-changelog --show-releases --renderer=markdown
RestructuredText¶
generate-changelog --show-releases --renderer=rest
Historical Markdown¶
generate-changelog --show-releases --renderer=historical-markdown
Jira integration¶
It’s possible to fetch ticket title and description from Jira. In order for it
to work, you should provide a fetch-title
and fetch-description
arguments:
generate-changelog --show-releases --fetch-title --fetch-description
In adddition to that, you should put valid Jira credentials into your
global .matyan.ini
configuration file.
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
Note, that placing .matyan.ini
into the home root will make that
configuration global for all projects. That’s however is handy, since local
.matyan.ini
files simply override the global ones. You could use global
configuration for instance for storing credentials to Jira.
[Jira]
url:https://barseghyanartur.atlassian.net/
username:user@domain.com
token:abcd1234
Tips and tricks¶
Write to file¶
generate-changelog --show-releases 2>&1 | tee changelog.md
Create initial config file¶
matyan-make-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: