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 and a Maven plugin
• Java 8 minimum requirement

Features:

• Checks the format against an extensive set of rules.
• Summarizes content to provide a quick overview of a repository.
• Filters and extracts versions for publication or searching.
• Modifies content to release unreleased changes.
• Manages GitHub, GitLab and Forgejo peculiarities.
• Validates semantic, calendar and regex versioning schemes.
• Handles the prefix tagging strategy.
• Seamlessly integrates into CI/CD pipelines.

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

Usage

Library

Heylogs is available as a Java library.
The Java API is straightforward and has a single point of entry:

Heylogs heylogs = Heylogs.ofServiceLoader();
Document flexmarkDocument = parseFileWithFlexmark(file);
Config config = Config.builder().versioningOf("semver").build();
List<Problem> problems = heylogs.check(flexmarkDocument, config);
...

Warning

This API is currently in beta and might change frequently.

Installation

<dependencies>
   <dependency>
      <groupId>com.github.nbbrd.heylogs</groupId>
      <artifactId>heylogs-api</artifactId>
      <version>_VERSION_</version>
   </dependency>
   <dependency>
      <groupId>com.github.nbbrd.heylogs</groupId>
      <artifactId>heylogs-ext-github</artifactId>
      <version>_VERSION_</version>
      <scope>runtime</scope>
   </dependency>
   ...
</dependencies>

GitHub action

Most probably, one wants to check the CHANGELOG.md file, thus the command is as follows:

- uses: jbangdev/[email protected]
  with:
    script: com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin
    scriptargs: "check -o result.json"

An alternative is to use the Maven command-line:

- run: mvn com.github.nbbrd.heylogs:heylogs-maven-plugin:_VERSION_:check -D heylogs.outputFile=result.json

Command-line tool

Heylogs CLI runs on any desktop operating system and requires Java 8 or later.
It follows the Unix philosophy of “Do one thing and do it well“ by performing a single function and beeing composable.

Composition example:

1. download a changelog (curl)
2. summarize its content as json (heylogs)
3. colorize the output (bat).

curl -s https://raw.githubusercontent.com/olivierlacan/keep-a-changelog/main/CHANGELOG.md | heylogs scan - -f json | bat -l json

Installation

The easiest way of installing the CLI is to use a package manager.
Each operating system has its own manager. See the list below for specific instructions.

Scoop

scoop bucket add nbbrd https://github.com/nbbrd/scoop-nbbrd.git
scoop install heylogs

Homebrew

brew install nbbrd/tap/heylogs

JBang

The CLI can be run by JBang almost anywhere using one of these options:

• Specific version (Maven coordinates): com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin
• Latest version (JBang catalog): heylogs@nbbrd

jbang com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin <command> [<args>]

docker run -v `pwd`:/ws --workdir=/ws jbangdev/jbang-action com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin <command> [<args>]

- uses: jbangdev/[email protected]
  with:
    script: com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin
    scriptargs: "<command> [<args>]"

Note that the trust parameter is required if the catalog is used instead of the Maven coordinates:
trust: https://github.com/nbbrd/jbang-catalog

Maven command-line

mvn dependency:copy -Dartifact=com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:jar:bin -DoutputDirectory=. -Dmdep.stripVersion -q
java -jar heylogs-cli-bin.jar <command> [<args>]

Zero installation

The CLI is a single executable jar, so it doesn't need to be installed to be used.
To use the CLI without installing it:

1. Download the latest jar binary (heylogs-_VERSION_-bin.jar) at:
   https://github.com/nbbrd/heylogs/releases/latest
2. Run this jar by calling:
   java -jar heylogs-cli-_VERSION_-bin.jar <command> [<args>]

Maven plugin

Heylogs Maven plugin allows the tool to be part of a Maven build workflow but can also be used as a standalone tool.

Examples

Check the changelog automatically on every build:

<plugin>
    <groupId>com.github.nbbrd.heylogs</groupId>
    <artifactId>heylogs-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>check</goal>
            </goals>
            <inherited>false</inherited>
        </execution>
    </executions>
    <configuration>
        <versioning>semver</versioning>
    </configuration>
</plugin>

Tip

Versioning, tagging and forge should be configured globally in the plugin configuration section instead of the execution configuration section to avoid repetition and basic mistakes.

This check can also be performed manually by calling it directly from the command-line:

mvn heylogs:check

Features

Heylogs provides several commands to interact with changelog files. These commands can be used through the CLI, the Maven plugin or the Java API.

Interface	Example
CLI	$ heylogs check --versioning semver
MVN	$ mvn com.github.nbbrd.heylogs:heylogs-maven-plugin::check -D heylogs.versioning=semver
API	Heylogs.ofServiceLoader().check(document, Config.builder().versioningOf("semver").build())

Commands: [ check | scan | extract | release | list ]

Heylogs also provides several customizations to adapt to various workflows. See forge, versioning and tagging sections below.

Note

The examples below use the CLI for the sake of simplicity. Command options are available through the --help option.

Check command

The check command checks the format against an extensive set of rules.

$ heylogs check
CHANGELOG.md

  No problem

Tip

A rule configuration can be modified by using the --rule option.

For example, upgrading the severity of the dot-space-link-style rule from OFF to WARN and disabling the no-empty-group rule can be done with the following command:
$ heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF

Scan command

The scan command summarizes the content of changelog files to provide a quick overview of a repository.

$ heylogs scan
CHANGELOG.md
  Valid changelog
  Found 20 releases
  Ranging from 2022-09-08 to 2025-07-24
  Compatible with Semantic Versioning
  Forged with GitHub at https://github.com/nbbrd/heylogs
  Has 1 unreleased changes

Extract command

The extract command filters and extracts versions for publication or searching.

$ heylogs extract --limit 1
## [Unreleased]

### Changed

- Switch to JSpecify [#143](https://github.com/nbbrd/heylogs/issues/143)

[Unreleased]: https://github.com/nbbrd/heylogs/compare/v0.11.1...HEAD

Release command

The release command modifies the content of a changelog file to release unreleased changes.

List command

The list command lists all the resources of the application.

Resources
  forge       forgejo  forgejo                   Forgejo                        
  forge       github   github                    GitHub                         
  forge       gitlab   gitlab                    GitLab                         
  format      api      stylish                   Human-readable output          
  format      json     json                      JSON-serialized output         
  rule        api      all-h2-contain-a-version  All H2 contain a version  ERROR
  rule        api      consistent-separator      Consistent separator      ERROR
  rule        api      date-displayed            Date displayed            ERROR
  rule        api      dot-space-link-style      Dot-space-link style      OFF  
  ...
  rule        api      versioning-format         Versioning format         ERROR
  tagging     api      prefix                    Prefix tagging                 
  versioning  api      regex                     Regex Versioning               
  versioning  calver   calver                    Calendar Versioning            
  versioning  semver   semver                    Semantic Versioning            
  
  27 resources found

Forge peculiarities

A forge doesn't only host the source code but also provides additional services such as issue tracking, pull/merge requests, CI/CD pipelines, etc. Heylogs is able to validate and, in some cases, modify the reference links of these services.

Heylogs supports the following forge references:

	Commit	Compare	Issue	Request	Mention
GitHub	✔	✔	✔	✔	✔
GitLab	✔	✔	✔	✔	✔
Forgejo	✔	✔	✔	✔	✔

Tip

Forge links are detected by using a list of default known hosts (e.g. github.com, gitlab.com, forgejo.org) but the detection can also be customized using the --domain option. For example: $ heylogs check --domain mygit.company.com:gitlab

Versioning schemes

As versions are usually not random strings, Heylogs supports several versioning schemes to validate them:

ID	Description	Example	Argument
semver	Semantic versioning	1.0.0	-
calver	Calendar versioning	2023.04.01	calver pattern
regex	Custom regex-based versioning	X13	regex pattern

Heylogs can detect the versioning scheme automatically when scanning a changelog, but you need to specify it explicitly to enable validation.

Examples:

• $ heylogs check -v semver
• $ heylogs check -v calver:YYYY.MM.DD
• $ heylogs check -v regex:X\d+

Tagging strategy

Versions and release tags are often linked for convenience. The most common convention is to use the version with a v prefix (i.e. version 1.0.0 is tagged as v1.0.0).

Heylogs supports the following tagging strategies:

ID	Description	Example	Argument
prefix	Tags with a common prefix	v1.0	non-empty string

Examples:

• $ heylogs check -t prefix:v

Cookbook

Badges

Heylogs makes it possible to generate badges for the unreleased changes of a changelog using a GitHub workflow and the shields.io API.

This workflow has the following steps:

1. it summarizes the changelog content into a json file
2. it converts this json file to a format that shields.io can understand
3. it pushes the result to a dedicated branch

Here are some examples:

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.