bulletins

Modular changelogs from bulletins.
A developer-friendly tool for managing changelogs as individual Markdown files, then compiling them into a single CHANGELOG.md.

✨ Features

• Add individual change bulletins (.md files) per feature, fix, or update
• Automatically compile all bulletins into a formatted CHANGELOG.md
• Semantic versioning using Git tags
• Can be applied retroactively by providing commit SHA in bulletin metadata
• Organizes changes under sections and subheadings
• Works well with branches and collaborative workflows

🚀 Getting Started

pip install bulletins

bulletins add      # create a new bulletin describing a change
bulletins compile  # compile all bulletins into a CHANGELOG.md

📁 Bulletin Format

Each bulletin is a .md file stored in the bulletins folder by default. For example:

---
sha: abc1234  <!-- Optional: Commit SHA -->
---

# Added

- Add support for multiline bulletin descriptions


# Fixed

## Tests

- Fix typo in unit test

When the commit SHA is not specified in the bulletin metadata, the commit in which the file was created is used.

Bulletin files are automatically grouped by headings when compiled into a single CHANGELOG.md file.

🏷️ Version Detection

bulletins determines versions from Git tags following semantic versioning to group changes under section in the CHANGELOG.md file. The default behavior is:

• Released versions from tags like v1.0.0 → shown as 1.0.0 (2025-06-18)
• Unreleased versions from the branch name, e.g. develop → shown as develop (Unreleased)

It is also possible to configure bulletins to determine the beginning point and name of unreleased versions from git tags, such as v1.0.1-pre, shown as 1.0.1 (Unreleased).

The version is determined from the closest matching tag to the bulletin's commit.

📦 Project Status

This tool is under active development. Contributions and feedback welcome.

📝 License

MIT License