Skip to main content

Generate changelog from Git commits.

Project description

Generate changelog from Git commits.

PyPI Version Supported Python versions Build Status MPL-1.1 OR GPL-2.0-only OR LGPL-2.1-or-later Coverage

Prerequisites

  • Python 3.6, 3.7, 3.8 and PyPy

Use cases and basic concepts

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).

How would you know it could be useful?

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.

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: 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

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.

Configuration

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

Tips and tricks

Write to file

generate-changelog --show-releases 2>&1 | tee changelog.md

Documentation

Documentation is available on Read the Docs.

Installation

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

Usage examples

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

Testing

Simply type:

./runtests.py

Or use tox:

tox

Or use tox to check specific env:

tox -e py36

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

Support

For any issues contact me at the e-mail given in the Author section.

Author

Artur Barseghyan <artur.barseghyan@gmail.com>

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matyan-0.0.2.tar.gz (38.5 kB view hashes)

Uploaded Source

Built Distribution

matyan-0.0.2-py2.py3-none-any.whl (31.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page