attribution 1.8.0
Generate changelogs based on tag messages and shortlogs
Requires Python: >=3.8

attribution
===========

Automate releases and changelogs based on commit tags and shortlogs.

.. image:: https://readthedocs.org/projects/attribution/badge/?version=stable
   :target: https://attribution.omnilib.dev/en/stable/
   :alt: Documentation Status
.. image:: https://img.shields.io/pypi/v/attribution.svg
   :target: https://pypi.org/project/attribution
   :alt: PyPI Release
.. image:: https://img.shields.io/badge/change-log-blue
   :target: https://github.com/omnilib/attribution/blob/main/CHANGELOG.md
   :alt: Changelog
.. image:: https://img.shields.io/pypi/l/aiosqlite.svg
   :target: https://github.com/omnilib/aiosqlite/blob/main/LICENSE
   :alt: MIT Licensed

attribution provides a simple tool for automating a basic release workflow
for Python projects. At its core, it generates Markdown-formatted changelogs
based on the version tags in your repository, and can both fit into existing
workflows, or automate the entire release preparation process with a single
command.

When generating a changelog, attribution will find all tag names starting with
"v" followed by a valid `PEP 440 version identifier`_. It will then use the
message from each tag, combined with the "shortlog", to generate an ordered
changelog that includes recognition for all contributers to your project.
The output can be saved to your preferred changelog file, or piped to other
tools as part of your release workflow:

.. _PEP 440 version identifier: https://www.python.org/dev/peps/pep-0440/#version-scheme

.. code-block:: shell-session

    $ attribution generate
    project name
    ============

    v0.2
    ----

    Another release

    ```
    $ git shortlog -s v0.1...v0.2
        1 Ash
        3 Misty
    ```

    v0.1
    ----

    First release

    ```
    $ git shortlog -s ...v0.1
        1 Ash
    ```

If you prefer and end-to-end solution, attribution can also be used for creating
release notes, updating a ``__version__.py`` file with a matching version,
and tagging a signed version bump commit containing the final changelog:

.. code-block:: shell-session

    $ attribution tag -m "Final release" 1.0
    $ head CHANGELOG.md
    project name
    ============

    v1.0
    ----

    Final release

    ```
    $ git shortlog -s v0.2...v1.0
        3 Ash
        2 Brock
    ```

attribution is a fully bootstrapped project. The `Changelog`_ is generated by
attribution, and from version 1.2.0 onward, all releases are created with
attribution as well.

.. _Changelog: https://attribution.omnilib.dev/en/latest/changelog.html


Install
-------

attribution requires Python 3.7 or newer.
You can install it from PyPI:

.. code-block:: shell-session

    $ pip install attribution

attribution should guess reasonable defaults for most common Python projects,
but for best results, you should initialize your project configuration:

.. code-block:: shell-session

    $ attribution init
    Project name [attribution]:
    Package namespace [attribution]:
    Use __version__.py file [Y/n]:

This will automatically add the appropriate configuration to your project's
``pyproject.toml``:

.. code-block:: toml

    [tool.attribution]
    name = "attribution"
    package = "attribution"
    version_file = true

More details can be found in the `User Guide`_.

.. _User Guide: https://attribution.omnilib.dev/en/stable/guide.html


License
-------

attribution is copyright `Amethyst Reese <https://noswap.com>`_, and licensed under
the MIT license. I am providing code in this repository to you under an open
source license. This is my personal repository; the license you receive to my
code is from me and not from my employer. See the `LICENSE`_ file for details.

.. _LICENSE: https://github.com/omnilib/attribution/blob/main/LICENSE