Skip to content

Configuration Settings for antsibull-changelog

This document describes all settings that are supported in changelogs/config.yaml.

General options

add_plugin_period (boolean)

The default value is false for existing configurations, and true for new configurations.

If set to false, the plugin short description is used. If set to true, a period is added to the end of the plugin short description if no other end punctuation is present. Setting to true complies with the Ansible changelog format.

always_refresh (string)

Allowed values are none, full, or a comma-separated combination of one or more of plugins, plugins-without-removal, fragments and fragments-without-archives.

If true is passed, it will be converted to full. If false is passed, it will be converted to none.

For details, see "Updating/Refreshing changelog.yaml" in the main documentation.

archive_path_template (optional string)

The default value is null.

When keep_fragments is set to false, and this setting is defined, fragments will be copied to the path specified by this setting after a release is made. This setting is assumed to point to a directory, and the placeholder {version} can be used to make the destination dependent on the version number of the new release. If the directory does not yet exist, it will be created.

changelog_filename_template (string)

The default value is CHANGELOG-v%s.rst for existing configurations, and ../CHANGELOG.rst for new configurations.

This is the path relative to the changelogs/ directory where the reStructuredText version of the changelog is written to. The placeholder %s will be replaced by the first changelog_filename_version_depth parts of the version of the release.

Note

The file extension (default .rst) will always be replaced by the extension matching the output format (see output_formats). Therefore the extension provided here will always be ignored.

changelog_filename_version_depth (integer)

The default value is 2 for existing configurations, and 0 for new configurations.

Determines the number of parts of the current release version to be used when replacing %s in changelog_filename_template (see above). For the value 2, version 1.2.3 will result in the string 1.2. The value 0 results in the empty string.

changes_file (string)

The default value is .changes.yaml for existing configurations, and changelog.yaml for new configurations.

The YAML file where the changelog is stored in a machine-readable form. This is relative to the changelogs/ directory and should not be changed, since changelogs/changelog.yaml is the standard place for the machine-readable file which is expected to be there by the Ansible Community Distribution changelog generator.

changes_format (string)

Must be set to combined.

All fragments and plugin data is stored inside the file (used by ansible-base, ansible-core, and in collections).

Note that support for classic has been REMOVED and the field is now required.

changelog_nice_yaml (boolean)

The default is false.

When set to true, the changelogs/changelog.yaml file will be written with a slightly different YAML encoding that is compatible with ansible-lint's default rules.

Note

The exact format used might be adjusted in the future if new releases of ansible-lint adjust their yamllint configuration.

changelog_sort (string)

The default is alphanumerical.

This option controls the sorting of changelog entries in changelogs/changelog.yaml. It accepts the following values:

  • unsorted: No sorting is performed on the changelog entries. The entries are stored in the order they were added.
  • version: Sorts the changelog entries by version in ascending order.
  • version_reversed: Sorts the changelog entries by version in descending order.
  • alphanumerical: Sorts the changelog entries in alphanumerical order.

flatmap (optional boolean)

The default value is null.

Can be set to true or false explicitly to enable respectively disable flatmapping. Since flatmapping is disabled by default (except for ansible-core), this is effectively only needed for the big community collections community.general and community.network.

When enabled, a plugin foo.bar.subdir.dir.plugin_name will be mentioned as plugin_name or foo.bar.plugin_name (if use_fqcn is true), instead of as subdir.dir.plugin_name respectively foo.bar.subdir.dir.plugin_name.

is_other_project (boolean)

The default value is false.

If set to true, does not look for galaxy.yml and does not look for new Ansible objects (plugins, modules and roles). This allows the changelog generator to be used for projects which are not ansible-core/-base or an Ansible collection.

ignore_other_fragment_extensions (boolean)

The default value is false for existing configurations, and true for new configurations.

If set to true, only .yml and .yaml fragment filenames are considered which do not start with a dot. This is compatible with what ansible-test sanity --test changelog enforces. If set to false (default if not specified), all filenames that do not start with a dot are considered.

keep_fragments (boolean)

The default value is false.

If set to false, the fragment files will be removed after a release is done. If set to true, fragment files for old releases are kept.

If fragment files should be moved to another directory after release, set this setting to false and set archive_path_template.

See also prevent_known_fragments.

mention_ancestor (boolean)

The default value is true.

If an ancestor is defined in changelogs/changelog.yaml, determines whether it should be mentioned at the beginning of the changelog or not. If set to true, This changelog describes changes after version {ancestor} will be inserted at the top of the changelog.

notes_dir (string)

The default value is fragments.

The name of the subdirectory of changelogs/ that contains the changelog fragments.

output_formats (list of strings)

The default is ["rst"].

A list of output formats to write the changelog as. Supported formats are rst for ReStructuredText and md for MarkDown.

prelude_name (string)

The default value is release_summary.

Name of the prelude section to be used in changelog fragments. This section is special, in that it does not accept a list, but a string.

prelude_title (string)

The default value is Release Summary.

The title for the section whose name is set in prelude_name.

prevent_known_fragments (optional boolean)

The default value is the same value as the keep_fragments option.

If set to true, will not add changelog fragments to a release whose filename was already used in the past. This was the default behavior before antsibull-changelog 0.9.0. From 0.9.0 on, it is set to false by default if keep_fragments is false.

If keep_fragments is set to false later-on when some fragments from older releases are still there, and you want to keep them, make sure to set prevent_known_fragments explicitly to true. Otherwise they will be added again to the next release.

sanitize_changelog (boolean)

The default value is false for existing configurations, and true for new configurations.

Remove all invalid and superfluous information when loading a changelogs/changelog.yaml file.

sections (list of two-element lists of strings)

The default value is:

- - major_changes
  - Major Changes
- - minor_changes
  - Minor Changes
- - breaking_changes
  - Breaking Changes / Porting Guide
- - deprecated_features
  - Deprecated Features
- - removed_features
  - Removed Features (previously deprecated)
- - security_fixes
  - Security Fixes
- - bugfixes
  - Bugfixes
- - known_issues
  - Known Issues

Lists all section names (first element) and their titles (second element). The only two sections not listed here are the prelude section (release_summary / "Release Summary") and the trivial section (trivial, no title).

It is not recommended to change this list, except possibly adjust section titles. Collections using other section names will cause problems with the Ansible Community Distribution changelog generation.

title (string)

The default value is the titlecase of the collection's namespace and name.

The title is shown at the top of the changelog.

trivial_section_name (optional string)

The default value is trivial for collections and other projects, and null for ansible-core/ansible-base.

This defines a section that is not included in the generated reStructuredText version of the changelog. It can be used to add changelog fragments to changes that are so minor (trivial) that they should not appear in the changelog, or that are irrelevant to the user (for example changes in the CI system used). When set to null, no trivial section is allowed.

use_fqcn (boolean)

The default value is false for existing configurations, and true for new configurations.

When set to true, uses FQCN (Fully Qualified Collection Names) when mentioning new plugins and modules. This means that namespace.name. is prepended to the plugin respectively module names.

vcs (optional string)

Allowed values are none, git, or auto. The default value is none for existing configurations and auto for new configurations.

Configures which Version Control System is used by the project, if any. Right now this is used when (re-)loading the plugin list for an Ansible collection. For that the project files are copied into a temporary directory tree so that ansible-doc can be used to extract the plugin documentation.

When set to none, all files inside the project's directory will be considered. When set to git, will use git ls-files to determine which files to consider (directories and files ignored by git will be ignored). When set to auto, will automatically detect whether the project is part of a Git repository or not.

Deprecated options

new_plugins_after_name (string)

The default value is '' (empty string).

This setting is not used.

Ansible-core/-base specific options

These options are only used for the changelog for ansible-core, i.e. in the ansible/ansible GitHub repository.

use_semantic_versioning (boolean)

The default value is false.

If set to true, assumes that ansible-core use semantic versioning instead of the classic Ansible version numbers. This is mainly relevant for pre-releases. If set to true, release_tag_re and pre_release_tag_re are ignored.

release_tag_re (string)

The default value is ((?:[\d.ab]|rc)+).

This value is used to detect versions that are proper release versions, and not prereleases. This is a regular expression matching the version string preprended with v.

This setting is ignored if use_semantic_versioning is set to true.

pre_release_tag_re (string)

The default value is (?P<pre_release>\.\d+(?:[ab]|rc)+\d*)$.

This value is used to detect versions that are prereleases. This is a regular expression matching the version string preprended with v.

This setting is ignored if use_semantic_versioning is set to true.