keepachangelog

Tool for parsing changelogs that are based on the keepachangelog.com standard. Changelogs can be dumped to JSON or YAML.


Keywords
changelog, json, keepachangelog, parser, ruby, yaml
License
MIT
Install
gem install keepachangelog -v 0.6.1

Documentation

build status coverage report Gem Version

Changelog parser and transformer

Ruby gem for parsing Changelogs based on the format described at keepachangelog.com.

The parser can read either a Markdown file or a folder structure with YAML files.

The output can be Markdown, YAML files or JSON.

Installation

Add this line to your application's Gemfile:

gem 'keepachangelog'

And then execute:

bundle

Or install it yourself as:

gem install keepachangelog

Usage

Command line

When using the parser there are four important options to pay attention to:

  • from - The input format
  • to - The output format
  • in - The input file or folder
  • out - The output folder (only used when output format is yaml)

See keepachangelog help parse for more information.

Markdown input

To dump a Changelog to JSON run the following command:

keepachangelog --in CHANGELOG.md --from md --to json

YAML input

You can also express your changelog in YAML files inside a folder structure where each version is its own folder containing each change in a YAML-file.

Here's an example of a folder structure:

changelog
├── 0.1.0
│   └── 1-first-merge-request.yaml
├── 0.2.0
│   └── 3-another-cool-mr.yaml
├── 0.3.0
│   ├── 8-fixing-some-stuff.yaml
│   └── 9-add-new-feature.yaml
└── unreleased
    └── 11-minor-patch.yaml

Each YAML-file should be in the following format:

---
title: The ability to perform Foo while Bar is active
merge_request: 11
issue: 42
author: "@chbr"
type: New
  • title: A single sentence that describes the change
  • merge_request: The ID of the MR or PR (optional)
  • issue: The ID of the issue (optional)
  • author: The author of the change (optional)
  • type: The type of change, for example New, Changed, Fixed, Removed or Security.

To turn this into a Markdown document, simply run keepachangelog --in ./changelog --from yaml --to md

You can add meta data to your changelog in the file meta.yaml, placed inside the changelog folder, like so:

---
title: My Change Log
intro: This is my change log and I am using a cool gem to generate it.
url: https://git.example.com/group/project

The following meta data is read:

  • title: The title at the top of the Change log
  • intro: A text shown directly below the title
  • url: A URL to the git repository, used to generate links for versions that follows the format <url>/compare/FROM..TO

From Ruby code

If you want to use the API from your own Ruby code:

require 'keepachangelog'
parser = Keepachangelog::MarkdownParser.load('CHANGELOG.md')
puts parser.to_json

Development

After checking out the repo, run bin/setup to install dependencies. Then, run grunt test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.