Skip to content
/ heylogs Public

Set of tools to deal with the keep-a-changelog format

License

Notifications You must be signed in to change notification settings

nbbrd/heylogs

Repository files navigation

heylogs

Download Changes

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:

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

GITHUB

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

WINDOWS

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

Homebrew

MACOS LINUX

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

WINDOWS MACOS LINUX

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

DOCKER

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

GITHUB

- 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

WINDOWS MACOS LINUX GITHUB

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

WINDOWS MACOS LINUX GITHUB

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:

default
with custom label
without icon
without label

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: