antsibull-changelog: Overview
If you use Ansible extensively, you have probably collected a lot of Ansible code over time: playbooks, roles, plugins and more. The best way to organize your Ansible content is to bundle it together into an “Ansible collection”. This can be a private Ansible collection on your git server or you can even make it available to the Ansible community through galaxy.ansible.com.
To track changes over time within your Ansible collections you should leverage the capabilities of antsibull-changelog.
Overview
antsibull-changelog CHANGELOG.rst simplifies the release process by creating a CHANGELOG.rst automatically with all the relevant information.
Before a release, contributors need only to make sure that each commit includes a so-called changelog “fragment“.
At the time of release, antsibull-changelog reads all the available fragments and combines them into a CHANGELOG.rst.
Here is an example of such a CHANGELOG.rst:
======================= Atix.Demo Release Notes ======================= .. contents:: Topics v1.0.0 ====== Major Changes ------------- - nginx - added new role to install nginx Bugfixes -------- - k8s_drain - Fix k8s_drain does not wait for single pod
Installation
antsibull-changelog pip can be installed directly with
$ python3 -m pip install antsibull-changelog
Initial configuration
Run antsibull-changelog init at the top of your collection repository to create the initial configuration.
$ antsibull-changelog init . Created fragments directory "/path/to/repo/changelogs/fragments" Created config file "/path/to/repo/changelogs/config.yaml"
Writing a changelog fragment
antsibull-changelog creates the CHANGELOG.rst, by looking at the fragments under changelogs/fragments.
For this reason, it is the responsibility of each contributor to the collection to add appropriate fragments to all commits.
The only exceptions are commits which add new modules or plugins to a collection: these are detected automatically by antsibull-changelog as long as there is a version_added key in the corresponding module/plugin code.
Changelog fragments are written in yaml format (as is the case for almost everything related to Ansible).
Each section in a changelog fragment denotes a specific change category (bugfixes, major_changes, etc.) and contains a list of all changes pertaining to that category.
Here is an example of a changelog fragment for a bugfix:
--- bugfixes: - k8s_drain - Fix k8s_drain does not wait for single pod
The official documentation on changelog fragments can be found here.
Linting
antsibull-changelog provides the sub-command lint which allows to check whether the syntax of your changelog fragments is correct.
To try it, just run the following at the top of your repository:
$ antsibull-changelog lint
If there is no output, it means that everything is fine.
Implementation as a pre-commit hook
You can run antsibull-changelog lint lint as a pre-commit hook to make sure that you never commit code with an invalid changelog fragment.
To do this, you can place the following script under /path/to/repo/.git/hooks/pre-commit:
#!/bin/sh # Check that changelog fragments have the correct syntax antsibull-changelog lint
Careful: This implies that you must have installed antsibull-changelog locally. Consider creating a Python environment for this purpose.
Implementation in a CI/CD pipeline
Alternatively, you can implement an antsibull-changelog step within your CI/CD pipeline.
Here is an example configuration for a GitLab CI/CD pipeline:
antsibull-changelog-lint:
stage: linting
image: ${CI_REGISTRY}/:latest
before_script:
- python3 -m pip install antsibull-changelog
- |
[ -f "requirements.yml" ]
&& ansible-galaxy install -r requirements.yml
script:
- antsibull-changelog lint
Creating a release
Once you have created the appropriate changelog fragments, you can create a new CHANGELOG.rst with:
$ antsibull-changelog release
By default, this updates the file CHANGELOG.rst and deletes all old fragments.
To determine the release version, antsibull-changelog reads the content of the galaxy.yml. It is thus very important to update that file accordingly before each release.
