The antsibull-changelog
tool allows you to create and update
changelogs for Ansible collections, that are similar to the ones
provided by Ansible itself in earlier versions, and that are compatible
to the combined Ansible Community Distribution changelogs.
The following instructions assume that antsibull has been properly
installed, for example via pip install antsibull-changelog
. This is
the preferred way to install antsibull-changelog
.
If you want to get the current main
branch with not yet released
changes, run
pip install https://github.com/ansible-community/antsibull-changelog/archive/main.tar.gz
.
If you cloned the git repository and want to run it from there with
poetry
, antsibull-changelog
has to be substituted with
poetry run antsibull-changelog
.
To set up antsibull-changelog
, run:
antsibull-changelog init /path/to/your/collection
This is the directory which contains galaxy.yml
. This creates
subdirectories changelogs/
and changelogs/fragments/
, and a
configuration file changelogs/config.yaml
. Adjust the configuration
file to your needs. The settings of highest interest are:
title
: This is by default the titlecase of your collection's namespace and name. Feel free to insert a nicer name here.output_formats
: This is by default[rst]
. Change this to[rst, md]
to output both a RST and MarkDown version of the changelog, or to[md]
to only output a MarkDown version.keep_fragments
: The default valuefalse
removes the fragment files after a release is done. If you prefer to keep fragment files for older releases, set this totrue
. If you want to remove fragments after a release, but archive them in another directory, you can use thearchive_path_template
option in combination withkeep_fragments: no
. See further below in the list for its usage.changelog_filename_template
: The default value../CHANGELOG.rst
is relative to thechangelogs/
directory.use_fqcn
: The default valuetrue
uses FQCN when mentioning new plugins and modules.flatmap
: Setting totrue
orfalse
explicitly enables resp. disables flatmapping. Since flatmapping is disabled by default (except for ansible-core/-base), this is effectively only needed for the big community collectionscommunity.general
andcommunity.network
.always_refresh
: See "Updating/Refreshing changelog.yaml" on refreshing changelog fragments and/or plugin descriptions.archive_path_template
: Ifkeep_fragments
is set tofalse
, andarchive_path_template
is set, fragments will be copied into the directory denoted byarchive_path_template
instead of being deleted. The directory is created if it does not exist. The placeholder{version}
can be used for the current collection version into which the fragment was included.
For a description of all configuration settings, see the separate document Configuration Settings for antsibull-changelog.
If you want to do a basic syntax check of changelog fragments, you can run:
antsibull-changelog lint
If you want to check a specific fragment, you can provide a path to it;
otherwise, all fragments in changelogs/fragments/
are checked. This
can be used in CI to avoid contributors to check in invalid changelog
fragments, or introduce new sections (by mistyping existing ones, or
simply guessing wrong names).
If antsibull-changelog lint
produces no output on stdout, and exits
with exit code 0, the changelog fragments are OK. If errors are found,
they are reported by one line in stdout for each error in the format
path/to/fragment:line:column:message
, and the program exits with exit
code 3. Other exit codes indicate problems with the command line or
during the execution of the linter.
To release a new version of a collection, you need to run:
antsibull-changelog release
inside your collection's tree. This assumes that galaxy.yml
exists
and its version is the version of the release you want to make. If that
file does not exist, or has a wrong value for version
, you can
explicitly specify the version you want to release:
antsibull-changelog release --version 1.0.0
You can also specify a release date with --date 2020-12-31
, if the
default (today) is not what you want.
When doing a release, the changelog generator will read all changelog
fragments which are not already mentioned in the changelog, and include
them in a new entry in changelogs/changelog.yaml
. It will also scan
metadata for all modules and plugins of your collection, and mention all
modules and plugins with version_added
equal to this version as new
modules/plugins.
The metadata for modules and plugins is stored in
changelogs/.plugin-cache.yaml
, and is only recalculated once the
release version changes. To force recollecting this data, either delete
the file, or specify the --reload-plugins
option to
antsibull-changelog release
. That file should not be added to
source control. We suggest to add it to your .gitignore
file, or use
the equivalent mechanism if you use another source control.
After running antsibull-changelog release
, you should check
changelogs/changelog.yaml
and the generated reStructuredText file (by
default CHANGELOG.rst
) in.
By default, the changelogs/changelog.yaml
file is the main source of
truth for antsibull-changelog. It is only modified when a new release is
done, and in that case existing entries for other versions than the
current one are not touched.
If the main source of truth should be the fragments, or the plugin sources, the refreshing options or config has to be used.
Please note that for plugins, a cache is created in
changelogs/.plugin-cache.yaml
. This cache is updated when the
generate
and release
subcommands are run, and the latest version
(for generate
) resp. the release version (for release
) differs from
the version recorded in the cache file. Regeneration can be enforced by
specifying the --reload-plugins
option.
Also note that refreshing plugins purges all plugins added by changelog fragments.
This means that if plugin descriptions should be updated, either the
plugin cache has to be deleted, or --reload-plugins
has to be
specified next to the refresh options/configuration. Refreshing can be
configured in different ways, either by the always_refresh
configuration setting, or three command line options --refresh
,
--refresh-plugins
and --refresh-fragments
. These can be specified
for both the generate
and release
subcommands.
-
The
always_refresh
configuration is a string with one of the following values:-
none
(default): equivalent to--refresh-plugins
,--refresh-fragments
, and--refresh
not specified; -
full
: equivalent to--refresh-plugins allow-removal --refresh-fragments with-archives
specified, or alternatively--refresh
; -
a comma-separated list, where the following entries are supported:
plugins
: equivalent to--refresh-plugins allow-removal
specified;plugins-without-removal
: equivalent to--refresh-plugins prevent-removal
specified;fragments
: equivalent to--refresh-fragments with-archives
specified;fragments-without-archives
: equivalent to--refresh-fragments without-archives
specified.
-
-
The
--refresh
command line parameter is equivalent to--refresh-plugins allow-removal --refresh-fragments with-archives
. -
--refresh-plugins
: if specified, plugin and module descriptions are updated from the plugin cache.allow-removal
(default): Plugin and module descriptions are updated. If a module or plugin does not exist in the cache, it will be removed from the changelog. Please note that if you do not start a new changelog per major release of a collection, and have removed plugins or modules before,--refresh plugins allow-removal
will remove earlier changelog entries from when these plugins resp. modules were added!prevent-removal
: Plugin and module descriptions are updated. If a module or plugin does not exist in the cache, it will not be removed from the changelog.
-
--refresh-fragments
: if specified, the fragments for all versions will be recreated from the changelog fragment files. This is only possible ifkeep_fragments
istrue
, or fragment archives exist (see thearchive_path_template
option). Note that if not all fragments were archived or kept in the fragments directory, they will be removed from the changelog.with-archives
(default): Uses both the archives and the current fragment directory to update the fragments.without-archives
: Uses only the current fragment directory to update the fragments. Fragments that have been moved to the archive and no longer exist in the fragment directory will vanish from the changelog.
This section describes the section categories created in the default config. You can change them, though this is strongly discouraged for collections which will be included in the Ansible Community Distribution.
The categories are the same as the ones in the Ansible-case changelog fragments.
!!! note
The changelog generator automatically detects new modules and
new plugins which are documentable (i.e. where you have DOCUMENTATION
where version_added
is there), so you do not need to create changelog
entries for them.
The full list of categories is:
release_summary
This is a special section: as opposed to a list of strings, it
accepts one string. This string will be inserted at the top of the
changelog entry for the current version, before any section. There
can only be one fragment with a release_summary
section. In
ansible-core, this is used for stating the release date and for
linking to the porting guide
(example,
result).
breaking_changes
This (new) category should list all changes to features which
absolutely require attention from users when upgrading, because an
existing behavior is changed. This is mostly what Ansible's Porting
Guide used to describe. This section should only appear in a initial
major release (x.0.0
) according to semantic
versioning.
major_changes
This category contains major changes to the collection. It should only contain a few items per major version, describing high-level changes. This section should not appear in patch releases according to semantic versioning.
minor_changes
This category should mention all new features, like plugin or module options. This section should not appear in patch releases according to semantic versioning.
removed_features
This category should mention all modules, plugins and features that
have been removed in this release. This section should only appear
in a initial major release (x.0.0
) according to semantic versioning.
deprecated_features
This category should contain all modules, plugins and features which have been deprecated and will be removed in a future release. This section should not appear in patch releases according to semantic versioning.
security_fixes
This category should mention all security relevant fixes, including CVEs if available.
bugfixes
This category should be a list of all bug fixes which fix a bug that was present in a previous version.
known_issues
This category should mention known issues that are currently not fixed or will not be fixed.
trivial
This category will not be shown in the changelog. It can be used to describe changes that are not touching user-facing code, like changes in tests. This is useful if every PR is required to have a changelog fragment.
There are some special categories starting with add
;
please see the next section for details.
A guide on how to write changelog fragments can be found in the Ansible docs.
Example of a regular changelog fragment:
bugfixes:
- docker_container - wait for removal of container if docker API returns early
(https://github.com/ansible/ansible/issues/65811).
The filename in this case was
changelogs/fragments/65854-docker_container-wait-for-removal.yml
,
because this was implemented in PR #65854 in
ansible/ansible.
A fragment can also contain multiple sections, or multiple entries in one section:
deprecated_features:
- docker_container - the ``trust_image_content`` option will be removed. It has always been ignored by the module.
- docker_stack - the return values ``err`` and ``out`` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead.
breaking_changes:
- "docker_container - no longer passes information on non-anonymous volumes or binds as ``Volumes`` to the Docker daemon. This increases compatibility with the ``docker`` CLI program. Note that if you specify ``volumes: strict`` in ``comparisons``, this could cause existing containers created with docker_container from Ansible 2.9 or earlier to restart."
The release_summary
section is special, in that it doesn't contain a
list of strings, but a string, and that only one such entry can be shown
in the changelog of a release. Usually for every release (pre-release or
regular release), at most one fragment is added which contains a
release_summary
, and this is only done by the person doing the
release. The release_summary
should include some global information on
the release; for example, in Ansible's
changelog,
it always mentions the release date and links to the porting guide.
An example of how a fragment with release_summary
could look like is
changelogs/fragments/0.2.0.yml
from community.general:
release_summary: |
This is the first proper release of the ``community.general`` collection on 2020-06-20.
The changelog describes all changes made to the modules and plugins included in this collection since Ansible 2.9.0.
Note that with ansible-core 2.11+, new roles are automatically detected
if their documentation (in the argument spec) contains an appropriate
version_added
value for the main
entrypoint. With ansible-core 2.14+
(or the current devel
and milestone
branches), filter and test
plugins are also automatically detected if their documentation contains
an appropriate version_added
value. No version of ansible-core allows
to document playbooks (yet), so new playbooks have to be documented as
described below.
The following describes a way to document new playbooks. When using
older versions of ansible-core during release time when the changelog is
generated, this can also be used to document new roles, test plugins,
and filter plugins. This works by using special sections in changelog
fragments whose names start with add
:
---
# Always needed for new playbooks:
add object.playbook:
- name: wipe_server
description: Wipes a server
# Only needed when ansible-core < 2.14 is used during the release process,
# or when the filter has no documentation or the documentation is missing a
# 'version_added' entry:
add plugin.filter:
- name: to_time_unit
description: Converts a time expression to a given unit
- name: to_seconds
description: Converts a time expression to seconds
# Only needed when ansible-core < 2.14 is used during the release process,
# or when the test has no documentation or the documentation is missing a
# 'version_added' entry:
add plugin.test:
- name: asn1time
description: Check whether the given string is an ASN.1 time
# Only needed when ansible-core < 2.11 is used during the release process,
# or when the role has no argument spec or the argument spec is missing a
# 'version_added' entry for the 'main' entrypoint:
add object.role:
- name: nginx
description: A nginx installation role
The following sections are considered as the Porting Guide of the collection. For collections included in Ansible, these will be inserted into Ansible's Porting Guide:
major_changes
breaking_changes
deprecated_features
removed_features