heylogs

heylogs is a set of tools to deal with the keep-a-changelog format, a changelog format designed to be human-readable. It can be used as a linter in interactive sessions and automations.

Key points:

• Available as a library, a command-line tool and a Maven plugin
• Java 8 minimum requirement

Features:

• Checks format
• Summarizes content
• Extracts versions
• Modify content

[ Library | Command-line tool | Maven plugin | Badges | Developing | Contributing | Licensing | Related work]

Library

Heylogs is available as a Java library.
Note that the API is currently in beta and might change frequently.

<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>

The API is straightforward and has a single point of entry:

Heylogs heylogs = Heylogs.ofServiceLoader();
Document flexmarkDocument = parseFileWithFlexmark(file);
List<Problem> problems = heylogs.checkFormat(flexmarkDocument);
...

WIP

Command-line tool

Heylogs CLI runs on any desktop operating system such as Microsoft Windows, Solaris OS, Apple macOS, Ubuntu and other various Linux distributions. It requires a Java SE Runtime Environment (JRE) version 8 or later to run on such as OpenJDK.

It provides the following commands:

Name	Description
check	Check format
scan	Summarize content
extract	Extract versions
release	Release changes
list	List resources

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

Using in a GitHub action

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

- uses: jbangdev/jbang-action@v0.110.1
  with:
    script: com.github.nbbrd.heylogs:heylogs-cli:_VERSION_:bin
    scriptargs: "check CHANGELOG.md"

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/jbang-action@v0.110.1
  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.

It provides the following goals:

Name	Description
check	Check format
scan	Summarize content
extract	Extract versions
release	Release changes
list	List resources

Examples

Check the changelog on every build:

<plugin>
    <groupId>com.github.nbbrd.heylogs</groupId>
    <artifactId>heylogs-maven-plugin</artifactId>
    <version>${heylogs.version}</version>
    <executions>
        <execution>
            <id>check-changelog</id>
            <goals>
                <goal>check</goal>
            </goals>
            <inherited>false</inherited>
            <configuration>
                <semver>true</semver>
            </configuration>
        </execution>
    </executions>
</plugin>

Extract the latest version from the changelog during a release:

<profile>
    <id>release</id>
    <build>
        <plugins>
            <plugin>
                <groupId>com.github.nbbrd.heylogs</groupId>
                <artifactId>heylogs-maven-plugin</artifactId>
                <version>${heylogs.version}</version>
                <executions>
                    <execution>
                        <id>extract-changelog</id>
                        <goals>
                            <goal>extract</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</profile>

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