Heylogs - communicate changes at scale

Heylogs is a tool designed to automate the validation and the release of changes in a human-readable format.

Key points:

• Follow the Keep a Changelog format.
• Available as a library, a command-line tool, a Maven plugin and Maven Enforcer rules.
• Java 8 minimum requirement

Features:

• Create changelog files, and list available resources and rules.
• Validate changelog format, summarize content, and extract or filter versions for publication or searching.
• Add, fetch, or set summaries for changes; release new versions or yank problematic releases.
• Integrate with GitHub, GitLab, and Forgejo; support semantic, calendar, and regex versioning; and handle tag prefix strategies.
• Automate workflows in CI/CD pipelines and support hierarchical configuration via heylogs.properties files.

[ Usage | Features | Cookbook | Developing | Contributing | Licensing | Related work]

Usage

Heylogs is available in multiple formats to fit your workflow:

• Library - Java API for programmatic access
• Command-line tool - Command-line tool for any platform
• Maven plugin - Maven build integration
• Maven Enforcer rules - Enforce changelog quality in builds
• CI/CD pipelines - Integrate into CI/CD environments

Features

Heylogs provides several commands to interact with changelog files:

• init - Create a new changelog file with a template
• check - Validate changelog format against an extensive set of rules
• scan - Summarize changelog content and metadata
• list - Display all available resources and rules
• extract - Filter and extract specific versions
• push - Insert a change entry to the Unreleased section
• fetch - Fetch a change from a forge issue or pull request into Unreleased
• note - Set or update the summary text after the Unreleased header
• release - Convert unreleased changes into a new release
• yank - Mark an existing release as yanked

Heylogs also provides some customizations to adapt to various workflows:

• forge - Support for GitHub, GitLab, and Forgejo specific features
• versioning - Validate version numbers using semver, calver, or custom regex patterns
• tagging - Configure version tag prefixes (e.g., v1.0.0)
• rules - Extensive set of rules to enforce changelog quality and consistency

Heylogs also has some quality-of-life features to make it easier to use and integrate into different workflows:

• config file - Hierarchical configuration through heylogs.properties files, similar to Lombok's configuration system

See the feature matrix for a summary of feature support by usage mode.

Cookbook

• badges - Generate badges for unreleased changes
• gitflow - Automate the changelog release
• tips - Tips and best practices for using Heylogs effectively

Developing

This project is written in Java and uses Apache Maven as a build tool.
It requires Java 8 as minimum version and all its dependencies are hosted on Maven Central.

The code can be build using any IDE or by just type-in the following commands in a terminal:

git clone https://github.com/nbbrd/heylogs.git
cd heylogs
mvn clean install

Contributing

Any contribution is welcome and should be done through pull requests and/or issues.

Licensing

The code of this project is licensed under the European Union Public Licence (EUPL).

Related work

This project is not the only one that deals with keep-a-changelog format.
Here is a non-exhaustive list of related work:

• clparse
• GIT Changelog Merge Driver - does a semantic merge of two changelogs.