{"id":6513,"library":"antsibull-changelog","title":"Antsibull Changelog","description":"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.","status":"active","version":"0.35.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/antsibull-changelog","tags":["ansible","changelog","documentation","build-tool","devops"],"install":[{"cmd":"pip install antsibull-changelog","lang":"bash","label":"Install antsibull-changelog"}],"dependencies":[{"reason":"YAML parsing for changelog fragments.","package":"pyyaml"},{"reason":"Version parsing and comparison.","package":"packaging"},{"reason":"Template rendering for changelog output.","package":"jinja2"},{"reason":"Parsing and manipulating dates.","package":"python-dateutil"},{"reason":"Validation of changelog fragment structure.","package":"jsonschema"},{"reason":"Enhanced terminal output.","package":"rich"}],"imports":[{"note":"The `cli.main` function is the entry point for the command-line tool, not typically used for programmatic library interaction.","wrong":"from antsibull_changelog.cli import main","symbol":"Changelog","correct":"from antsibull_changelog.changelog import Changelog"},{"symbol":"ChangelogFragment","correct":"from antsibull_changelog.fragment import ChangelogFragment"}],"quickstart":{"code":"from antsibull_changelog.changelog import Changelog\nfrom antsibull_changelog.fragment import ChangelogFragment\n\n# Simulate a changelog fragment content (normally read from a .yaml file)\nfragment_content = \"\"\"\nfragment:\n  - type: feature\n    description: Add new awesome feature.\n    section: Features\n    authors:\n      - John Doe\n\"\"\"\n\n# Parse a fragment from a string (or use ChangelogFragment.from_file())\ntry:\n    fragment = ChangelogFragment.from_string(\"my_first_feature.yaml\", fragment_content)\n\n    # Create a Changelog object and add the fragment\n    changelog = Changelog()\n    changelog.add_fragment(fragment)\n\n    print(f\"Successfully parsed fragment type: {fragment.type}\")\n    print(f\"Fragment description: {fragment.description}\")\n    print(f\"Total fragments in Changelog object: {len(changelog.fragments)}\")\nexcept Exception as e:\n    print(f\"Error parsing fragment: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install antsibull-changelog'.","cause":"The 'antsibull-changelog' package is not installed or not available in the current Python environment.","error":"ModuleNotFoundError: No module named 'antsibull_changelog'"},{"fix":"Ensure the correct import statement: 'from antsibull_changelog.cli import release'.","cause":"The 'release' function is not available in the 'antsibull_changelog' module, possibly due to an incorrect import statement.","error":"ImportError: cannot import name 'release' from 'antsibull_changelog'"},{"fix":"Create the 'changelogs/config.yaml' file in your project's root directory or specify the correct path.","cause":"The 'changelogs/config.yaml' configuration file is missing or not located in the expected directory.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'changelogs/config.yaml'"},{"fix":"Ensure the version number follows semantic versioning, e.g., '1.0.0'.","cause":"The version number provided is not recognized as a valid format by the 'antsibull-changelog' tool.","error":"ValueError: Invalid version number: '0.35.0'"},{"fix":"Verify that all required inputs are provided and correctly formatted before running the tool.","cause":"A function in 'antsibull_changelog' is attempting to iterate over a 'None' object, likely due to missing or incorrect input data.","error":"TypeError: 'NoneType' object is not iterable"}]}