Antsibull Changelog

0.35.0 verified Wed Apr 15 auth: no python

Antsibull Changelog is a Python tool designed to generate changelogs for Ansible-core and Ansible collections. It processes changelog fragments (YAML files) to produce structured changelog outputs. Currently at version 0.35.0, it undergoes active development with releases aligned to the broader Ansible ecosystem's needs and feature cycles.

pip install antsibull-changelog

Common errors

error ModuleNotFoundError: No module named 'antsibull_changelog' ↓

cause The 'antsibull-changelog' package is not installed or not available in the current Python environment.

fix

Install the package using pip: 'pip install antsibull-changelog'.

error ImportError: cannot import name 'release' from 'antsibull_changelog' ↓

cause The 'release' function is not available in the 'antsibull_changelog' module, possibly due to an incorrect import statement.

fix

Ensure the correct import statement: 'from antsibull_changelog.cli import release'.

error FileNotFoundError: [Errno 2] No such file or directory: 'changelogs/config.yaml' ↓

cause The 'changelogs/config.yaml' configuration file is missing or not located in the expected directory.

fix

Create the 'changelogs/config.yaml' file in your project's root directory or specify the correct path.

error ValueError: Invalid version number: '0.35.0' ↓

cause The version number provided is not recognized as a valid format by the 'antsibull-changelog' tool.

fix

Ensure the version number follows semantic versioning, e.g., '1.0.0'.

error TypeError: 'NoneType' object is not iterable ↓

cause A function in 'antsibull_changelog' is attempting to iterate over a 'None' object, likely due to missing or incorrect input data.

fix

Verify that all required inputs are provided and correctly formatted before running the tool.

Warnings

gotcha Primarily a CLI Tool: Many users expect a straightforward Python API to generate the full changelog like the CLI tool. However, the library's Python API is more granular, focusing on parsing fragments and managing changelog data. Direct programmatic generation mirroring the CLI often requires setting up file paths, configurations, and interacting with lower-level build functions. ↓

fix For full changelog generation, prefer using the `antsibull-changelog` command-line interface. For programmatic use, focus on interacting with `ChangelogFragment` and `Changelog` classes for data manipulation.

breaking Python Version Requirement: `antsibull-changelog` strictly requires Python 3.9 or newer. Attempting to install or run it on older Python versions (e.g., Python 3.8 or 3.7) will result in installation failures or runtime errors. ↓

fix Ensure your development environment is running Python 3.9 or a newer version (e.g., 3.10, 3.11, 3.12). Use a virtual environment to manage specific Python versions for your projects.

gotcha Changelog Fragment Structure: `antsibull-changelog` relies on a very specific YAML structure for its fragments. Deviations from the expected schema (e.g., incorrect top-level key, missing required fields, invalid types) will lead to parsing and validation errors. ↓

fix Always consult the official `antsibull-changelog` documentation for the correct changelog fragment YAML schema. Validate fragments using the `antsibull-changelog fragment --validate` command during development.

Imports

Changelog
wrong
```
from antsibull_changelog.cli import main
```
correct
```
from antsibull_changelog.changelog import Changelog
```
The `cli.main` function is the entry point for the command-line tool, not typically used for programmatic library interaction.

ChangelogFragment

from antsibull_changelog.fragment import ChangelogFragment

Quickstart

This quickstart demonstrates how to programmatically parse a changelog fragment and add it to a Changelog object. While `antsibull-changelog` is primarily a CLI tool, its core components can be used for custom changelog processing within Python applications. This example shows basic interaction with fragments, which are the building blocks of the changelog.

from antsibull_changelog.changelog import Changelog
from antsibull_changelog.fragment import ChangelogFragment

# Simulate a changelog fragment content (normally read from a .yaml file)
fragment_content = """
fragment:
  - type: feature
    description: Add new awesome feature.
    section: Features
    authors:
      - John Doe
"""

# Parse a fragment from a string (or use ChangelogFragment.from_file())
try:
    fragment = ChangelogFragment.from_string("my_first_feature.yaml", fragment_content)

    # Create a Changelog object and add the fragment
    changelog = Changelog()
    changelog.add_fragment(fragment)

    print(f"Successfully parsed fragment type: {fragment.type}")
    print(f"Fragment description: {fragment.description}")
    print(f"Total fragments in Changelog object: {len(changelog.fragments)}")
except Exception as e:
    print(f"Error parsing fragment: {e}")