Metadata-Version: 2.3
Name: antsibull-changelog
Version: 0.31.1
Summary: Changelog tool for Ansible-core and Ansible collections
Project-URL: Documentation, https://ansible.readthedocs.io/projects/antsibull-changelog/
Project-URL: Source code, https://github.com/ansible-community/antsibull-changelog/
Project-URL: Code of Conduct, https://docs.ansible.com/ansible/latest/community/code_of_conduct.html
Project-URL: Bug tracker, https://github.com/ansible-community/antsibull-changelog/issues
Project-URL: Changelog, https://github.com/ansible-community/antsibull-changelog/tree/main/CHANGELOG.md
Author-email: Felix Fontein <felix@fontein.de>, Toshio Kuratomi <a.badger@gmail.com>, Matt Clay <matt@mystile.com>
Maintainer-email: Felix Fontein <felix@fontein.de>, Maxwell G <maxwell@gtmx.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSES/GPL-3.0-or-later.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Ansible
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9.0
Requires-Dist: antsibull-docutils<2.0.0,>=1.0.0
Requires-Dist: antsibull-fileutils<2.0.0,>=1.0.0
Requires-Dist: docutils
Requires-Dist: packaging
Requires-Dist: rstcheck<7.0.0,>=3.0.0
Requires-Dist: semantic-version
Provides-Extra: codeqa
Requires-Dist: flake8>=3.8.0; extra == 'codeqa'
Requires-Dist: pylint; extra == 'codeqa'
Requires-Dist: reuse; extra == 'codeqa'
Provides-Extra: coverage
Requires-Dist: coverage[toml]; extra == 'coverage'
Provides-Extra: dev
Requires-Dist: black>=24; extra == 'dev'
Requires-Dist: coverage[toml]; extra == 'dev'
Requires-Dist: flake8>=3.8.0; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: nox; extra == 'dev'
Requires-Dist: pylint; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-error-for-skips; extra == 'dev'
Requires-Dist: reuse; extra == 'dev'
Requires-Dist: types-docutils; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-toml; extra == 'dev'
Provides-Extra: formatters
Requires-Dist: black>=24; extra == 'formatters'
Requires-Dist: isort; extra == 'formatters'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-error-for-skips; extra == 'test'
Provides-Extra: toml
Requires-Dist: tomli; (python_version < '3.11') and extra == 'toml'
Provides-Extra: typing
Requires-Dist: mypy; extra == 'typing'
Requires-Dist: types-docutils; extra == 'typing'
Requires-Dist: types-pyyaml; extra == 'typing'
Requires-Dist: types-toml; extra == 'typing'
Description-Content-Type: text/markdown

<!--
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later
-->

# antsibull-changelog -- Ansible Changelog Tool
[![Discuss on Matrix at #antsibull:ansible.com](https://img.shields.io/matrix/antsibull:ansible.com.svg?server_fqdn=ansible-accounts.ems.host&label=Discuss%20on%20Matrix%20at%20%23antsibull:ansible.com&logo=matrix)](https://matrix.to/#/#antsibull:ansible.com)
[![Nox badge](https://github.com/ansible-community/antsibull-changelog/workflows/nox/badge.svg?event=push&branch=main)](https://github.com/ansible-community/antsibull-changelog/actions?query=workflow%3A%22nox%22+branch%3Amain)
[![Codecov badge](https://img.shields.io/codecov/c/github/ansible-community/antsibull-changelog)](https://codecov.io/gh/ansible-community/antsibull-changelog)
[![REUSE status](https://api.reuse.software/badge/github.com/ansible-community/antsibull-changelog)](https://api.reuse.software/info/github.com/ansible-community/antsibull-changelog)

A changelog generator used by ansible-core and Ansible collections.

- Using the
  [`antsibull-changelog` CLI tool for collections](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelogs.md).
- Using the
  [`antsibull-changelog` CLI tool for other projects](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/other-projects.md).
- Documentation on the [`changelogs/config.yaml` configuration file for `antsibull-changelog`](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelog-configuration.md).
- Documentation on the
  [`changelog.yaml` format](https://github.com/ansible-community/antsibull-changelog/tree/main/docs/changelog.yaml-format.md).

antsibull-changelog is covered by the [Ansible Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).

## Community

Need help or want to discuss the project? See our [Community guide](https://ansible.readthedocs.io/projects/antsibull-changelog/community/) to learn how to join the conversation!

## Installation

It can be installed with pip:

    pip install antsibull-changelog

For python projects, `antsibull-changelog release` can retrieve the current
version from `pyproject.toml`.
You can install the project with

    pip install antsibull-changelog[toml]

to pull in the necessary toml parser for this feature.
The `toml` extra is always available, but it is noop on Python >= 3.11,
as `tomllib` is part of the standard library.

For more information, see the [documentation](https://ansible.readthedocs.io/projects/antsibull-changelog/).

## Development

Install and run `nox` to run all tests. That's it for simple contributions!
`nox` will create virtual environments in `.nox` inside the checked out project
and install the requirements needed to run the tests there.

---

antsibull-changelog depends on the sister antsibull-docutils and antsibull-fileutils projects.
By default, `nox` will install a development version of these projects from Github.
If you're hacking on antsibull-docutils and/or antsibull-fileutils alongside antsibull-changelog,
nox will automatically install these projects from  `../antsibull-docutils` and `../antsibull-fileutils`
when running tests if those paths exist.
You can change this behavior through the `OTHER_ANTSIBULL_MODE` env var:

- `OTHER_ANTSIBULL_MODE=auto` — the default behavior described above
- `OTHER_ANTSIBULL_MODE=local` — install the projects from `../antsibull-docutils`
  and `../antsibull-fileutils`.
  Fail if those paths don't exist.
- `OTHER_ANTSIBULL_MODE=git` — install the projects from the Github main branch
- `OTHER_ANTSIBULL_MODE=pypi` — install the latest versions from PyPI

---

To run specific tests:

1. `nox -e test` to only run unit tests;
2. `nox -e integration` to only run integration tests; this runs
   `antsibull-changelog lint` against antsibull-changelog and community.general
   (after cloning its repository) and records coverage data.
3. `nox -e coverage` to display combined coverage results after running `nox -e
   test integration`;
4. `nox -e lint` to run all linters and formatters at once;
5. `nox -e formatters` to run `isort` and `black`;
3. `nox -e codeqa` to run `flake8`, `pylint`, `reuse lint`, and `antsibull-changelog lint`;
7. `nox -e typing` to run `mypy`.

## Creating a new release:

1. Run `nox -e bump -- <version> <release_summary_message>`. This:
   * Bumps the package version in `src/antsibull_changelog/__init__.py`.
   * Creates `changelogs/fragments/<version>.yml` with a `release_summary` section.
   * Runs `antsibull-changelog release` and adds the changed files to git.
   * Commits with message `Release <version>.` and runs `git tag -a -m 'antsibull-changelog <version>' <version>`.
   * Runs `hatch build --clean`.
2. Run `git push` to the appropriate remotes.
3. Once CI passes on GitHub, run `nox -e publish`. This:
   * Runs `hatch publish`;
   * Bumps the version to `<version>.post0`;
   * Adds the changed file to git and run `git commit -m 'Post-release version bump.'`;
4. Run `git push --follow-tags` to the appropriate remotes and create a GitHub release.

## License

Unless otherwise noted in the code, it is licensed under the terms of the GNU
General Public License v3 or, at your option, later. See
[LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-community/antsibull-changelog/tree/main/LICENSE)
for a copy of the license.

The repository follows the [REUSE Specification](https://reuse.software/spec/) for declaring copyright and
licensing information. The only exception are changelog fragments in ``changelog/fragments/``.
