1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
``chango``
==========
.. image:: staimg/pypi-chango.svg
:target: https://pypi.org/project/chango/
:alt: PyPi Package Version
.. image:: staimg/pyversion-chango.svg
:target: https://pypi.org/project/chango/
:alt: Supported Python versions
.. image:: staimg/readthedocs-badge.svg
:target: https://chango.readthedocs.io/
:alt: Documentation Status
.. image:: staimg/license-chango.svg
:target: https://mit-license.org/
:alt: MIT License
.. image:: staimg/unit-test-badge.svg
:target: https://github.com/Bibo-Joshi/chango/
:alt: Github Actions workflow
.. image:: staimg/codecov-badge.svg
:target: https://codecov.io/gh/Bibo-Joshi/chango
:alt: Code coverage
.. image:: staimg/main.svg
:target: https://results.pre-commit.ci/latest/github/Bibo-Joshi/chango/main
:alt: pre-commit.ci status
.. image:: staimg/githubusercontent.svg
:target: https://github.com/astral-sh/ruff
:alt: Ruff
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
.. code:: shell
pipx install chango --upgrade
Note that installation via `pipx <https://pipx.pypa.io/stable/>`_ 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 <https://towncrier.readthedocs.io/>`_ and `reno <https://reno.readthedocs.io/>`_ 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.
.. code:: python
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.
.. code:: toml
[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
.. code:: shell
chango new short-slug-for-the-change
For more information on how to use ``chango``, please refer to the `documentation <https://chango.readthedocs.io/>`_.
|
