``chango``
==========
.. image:: https://img.shields.io/pypi/v/chango.svg
:target: https://pypi.org/project/chango/
:alt: PyPi Package Version
.. image:: https://img.shields.io/pypi/pyversions/chango.svg
:target: https://pypi.org/project/chango/
:alt: Supported Python versions
.. image:: https://readthedocs.org/projects/chango/badge/?version=stable
:target: https://chango.readthedocs.io/
:alt: Documentation Status
.. image:: https://img.shields.io/pypi/l/chango.svg
:target: https://mit-license.org/
:alt: MIT License
.. image:: https://github.com/Bibo-Joshi/chango/actions/workflows/unit_tests.yml/badge.svg?branch=main
:target: https://github.com/Bibo-Joshi/chango/
:alt: Github Actions workflow
.. image:: https://codecov.io/gh/Bibo-Joshi/chango/graph/badge.svg?token=H1HUA2FDR3
:target: https://codecov.io/gh/Bibo-Joshi/chango
:alt: Code coverage
.. image:: https://results.pre-commit.ci/badge/github/Bibo-Joshi/chango/main.svg
:target: https://results.pre-commit.ci/latest/github/Bibo-Joshi/chango/main
:alt: pre-commit.ci status
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
: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/>`_.
Raw data
{
"_id": null,
"home_page": null,
"name": "chango",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "changelog, development, releasenotes, versioning",
"author": null,
"author_email": "Hinrich Mahler <chango@mahlerhome.de>",
"download_url": "https://files.pythonhosted.org/packages/30/af/516302f2ec5078fedea522f011cbb1ff0abddc9cb5074ea67cde5a5fe994/chango-0.1.0.tar.gz",
"platform": null,
"description": "``chango``\n==========\n\n.. image:: https://img.shields.io/pypi/v/chango.svg\n :target: https://pypi.org/project/chango/\n :alt: PyPi Package Version\n\n.. image:: https://img.shields.io/pypi/pyversions/chango.svg\n :target: https://pypi.org/project/chango/\n :alt: Supported Python versions\n\n.. image:: https://readthedocs.org/projects/chango/badge/?version=stable\n :target: https://chango.readthedocs.io/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/pypi/l/chango.svg\n :target: https://mit-license.org/\n :alt: MIT License\n\n.. image:: https://github.com/Bibo-Joshi/chango/actions/workflows/unit_tests.yml/badge.svg?branch=main\n :target: https://github.com/Bibo-Joshi/chango/\n :alt: Github Actions workflow\n\n.. image:: https://codecov.io/gh/Bibo-Joshi/chango/graph/badge.svg?token=H1HUA2FDR3\n :target: https://codecov.io/gh/Bibo-Joshi/chango\n :alt: Code coverage\n\n.. image:: https://results.pre-commit.ci/badge/github/Bibo-Joshi/chango/main.svg\n :target: https://results.pre-commit.ci/latest/github/Bibo-Joshi/chango/main\n :alt: pre-commit.ci status\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n :target: https://github.com/astral-sh/ruff\n :alt: Ruff\n\nIntroduction\n------------\n\n``chango`` is a changelog generation tool.\nChanges are described alongside the code changes in the codebase.\n``chango`` extracts these changes and generates a changelog.\n``chango`` consists of both a command line interface and a Python API.\nAll aspects of the data formats, storage, and rendering are customizable via an interface class approach.\n\nInstalling\n----------\n\nYou can install or upgrade ``chango`` via\n\n.. code:: shell\n\n pipx install chango --upgrade\n\nNote that installation via `pipx <https://pipx.pypa.io/stable/>`_ is recommended since ``chango`` should not interfere with your projects dependencies.\n\nMotivation\n----------\n\nInformative and helpful changelogs (or release notes) are an essential part of software development.\nThey are a core part of the communication between developers and users.\nAt 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.\n``chango`` aims to make the process of maintaining changelogs as easy as possible.\nThis is achieved roughly by two means:\n\n1. **Shifting the creation of changelogs to the time of development**:\n Changes are described alongside the code changes in the codebase.\n This reduces the chance to forget about crucial details in the changes that should be mentioned in the changelog.\n It also ensures that the changelog undergoes the same review process as the code changes.\n2. **Automating the generation of changelogs**:\n ``chango`` extracts the changes from the codebase and generates a changelog.\n At release time, the changelog is thus already up-to-date and requires close to zero manual work.\n\nInspiration\n~~~~~~~~~~~\n\nThis package is heavily inspired by the `towncrier <https://towncrier.readthedocs.io/>`_ and `reno <https://reno.readthedocs.io/>`_ packages.\nBoth packages are excellent tools for changelog generation but are rather specialized in their use cases.\n``chango`` aims to be more flexible and customizable than these packages.\n\nQuick Start\n-----------\n\nA minimal setup of using ``chango`` for your project consists of the following steps.\n\nBuilding a ``ChanGo`` instance\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``chango`` is designed to be highly customizable.\n\nStore the following code in a file named ``chango.py`` in the root of your project.\n\n.. code:: python\n\n from chango.concrete import (\n CommentChangeNote,\n CommentVersionNote,\n DirectoryChanGo,\n DirectoryVersionScanner,\n HeaderVersionHistory,\n )\n\n chango_instance = DirectoryChanGo(\n change_note_type=CommentChangeNote,\n version_note_type=CommentVersionNote,\n version_history_type=HeaderVersionHistory,\n scanner=DirectoryVersionScanner(\n base_directory=\"changes\", unreleased_directory=\"unreleased\"\n ),\n )\n\nCreate the directories ``changes`` and ``changes/unreleased`` in the root of your project.\n\nThe ``chango_instance`` is the object that the CLI will use to interact with the changelog.\nIt contains information about the data type of individual changes, versions and the history of versions.\nIt also has instructions on how the individual changes are stored and how they are extracted from the codebase.\nAll these aspects can be customized by providing different classes to the ``DirectoryChanGo`` constructor or using a different implementation of the ``ChanGo`` interface.\n\nConfiguring ``pyproject.toml``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWe still need to make the ``chango`` CLI aware of the ``chango_instance``.\nThis is done by adding the following lines to your ``pyproject.toml`` file.\n\n.. code:: toml\n\n [tool.chango]\n sys_path = \".\"\n chango_instance = { name= \"chango_instance\", module = \"chango\" }\n\nThis instructs the CLI to import the ``chango_instance`` from the file ``chango.py`` in the root of your project.\n\nAdding Changes\n~~~~~~~~~~~~~~~\n\nNow the ``chango`` CLI is ready to be used.\nGo ahead and add a change to the ``changes/unreleased`` directory.\nIt's as simple als calling\n\n.. code:: shell\n\n chango new short-slug-for-the-change\n\nFor more information on how to use ``chango``, please refer to the `documentation <https://chango.readthedocs.io/>`_.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CHANgelog GOvernor for Your Project",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://chango.readthedocs.io/",
"Issues": "https://github.com/Bibo-Joshi/chango/issues",
"Source": "https://github.com/Bibo-Joshi/chango"
},
"split_keywords": [
"changelog",
" development",
" releasenotes",
" versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62580c965266917846c1780a742f917e8b2197f64e163c7ddc67c26868c6fa8b",
"md5": "f72178789b2a3d650c881d780ac56ab1",
"sha256": "72e5957b05c6fd4ce74b456129ad601896184d8a4a913c691d81ba4b76dcc9c6"
},
"downloads": -1,
"filename": "chango-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f72178789b2a3d650c881d780ac56ab1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 4247,
"upload_time": "2024-12-15T11:59:07",
"upload_time_iso_8601": "2024-12-15T11:59:07.997842Z",
"url": "https://files.pythonhosted.org/packages/62/58/0c965266917846c1780a742f917e8b2197f64e163c7ddc67c26868c6fa8b/chango-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "30af516302f2ec5078fedea522f011cbb1ff0abddc9cb5074ea67cde5a5fe994",
"md5": "304218f8ab3df1943c3adf1edacced3a",
"sha256": "3981c3458a4a18fa53cf658433e5fb5e4442ac50e273d30b2784294615aa56f1"
},
"downloads": -1,
"filename": "chango-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "304218f8ab3df1943c3adf1edacced3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 25712,
"upload_time": "2024-12-15T11:59:09",
"upload_time_iso_8601": "2024-12-15T11:59:09.535585Z",
"url": "https://files.pythonhosted.org/packages/30/af/516302f2ec5078fedea522f011cbb1ff0abddc9cb5074ea67cde5a5fe994/chango-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 11:59:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Bibo-Joshi",
"github_project": "chango",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chango"
}
JSON
