chango 0.6.1

CHANgelog GOvernor for Your Project

Introduction

chango is a changelog generation tool. Changes are described alongside the code changes in the codebase. chango extracts these changes and generates a changelog. chango consists of both a command line interface and a Python API. All aspects of the data formats, storage, and rendering are customizable via an interface class approach.

Installing

You can install or upgrade chango via

pipx install chango --upgrade

Note that installation via pipx is recommended since chango should not interfere with your projects dependencies.

Motivation

Informative and helpful changelogs (or release notes) are an essential part of software development. They are a core part of the communication between developers and users. At the same time, creating and maintaining changelogs can be a tedious and error-prone task, especially since this is often done only when a new release is prepared. chango aims to make the process of maintaining changelogs as easy as possible. This is achieved roughly by two means:

1. Shifting the creation of changelogs to the time of development: Changes are described alongside the code changes in the codebase. This reduces the chance to forget about crucial details in the changes that should be mentioned in the changelog. It also ensures that the changelog undergoes the same review process as the code changes.

2. Automating the generation of changelogs: chango extracts the changes from the codebase and generates a changelog. At release time, the changelog is thus already up-to-date and requires close to zero manual work.

Inspiration

This package is heavily inspired by the towncrier and reno packages. Both packages are excellent tools for changelog generation but are rather specialized in their use cases. chango aims to be more flexible and customizable than these packages.

Quick Start

A minimal setup of using chango for your project consists of the following steps.

Building a ChanGo instance

chango is designed to be highly customizable.

Store the following code in a file named chango.py in the root of your project.

from chango.concrete import (
    CommentChangeNote,
    CommentVersionNote,
    DirectoryChanGo,
    DirectoryVersionScanner,
    HeaderVersionHistory,
)

chango_instance = DirectoryChanGo(
    change_note_type=CommentChangeNote,
    version_note_type=CommentVersionNote,
    version_history_type=HeaderVersionHistory,
    scanner=DirectoryVersionScanner(
        base_directory="changes", unreleased_directory="unreleased"
    ),
)

Create the directories changes and changes/unreleased in the root of your project.

The chango_instance is the object that the CLI will use to interact with the changelog. It contains information about the data type of individual changes, versions and the history of versions. It also has instructions on how the individual changes are stored and how they are extracted from the codebase. All these aspects can be customized by providing different classes to the DirectoryChanGo constructor or using a different implementation of the ChanGo interface.

Configuring pyproject.toml

We still need to make the chango CLI aware of the chango_instance. This is done by adding the following lines to your pyproject.toml file.

[tool.chango]
sys_path = "."
chango_instance = { name= "chango_instance", module = "chango" }

This instructs the CLI to import the chango_instance from the file chango.py in the root of your project.

Adding Changes

Now the chango CLI is ready to be used. Go ahead and add a change to the changes/unreleased directory. It’s as simple als calling

chango new short-slug-for-the-change

For more information on how to use chango, please refer to the documentation.