Tool for parsing changelogs that are based on the keepachangelog.com standard. Changelogs can be dumped to JSON or YAML.
Homepage Rubygems Documentation Download
gem install keepachangelog -v 0.6.1
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.
Add this line to your application's Gemfile:
gem 'keepachangelog'
And then execute:
bundle
Or install it yourself as:
gem install keepachangelog
When using the parser there are four important options to pay attention to:
from
- The input formatto
- The output formatin
- The input file or folderout
- The output folder (only used when output format is yaml
)See keepachangelog help parse
for more information.
To dump a Changelog to JSON run the following command:
keepachangelog --in CHANGELOG.md --from md --to json
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 changemerge_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 logintro
: A text shown directly below the titleurl
: A URL to the git repository, used to generate links for versions
that follows the format <url>/compare/FROM..TO
If you want to use the API from your own Ruby code:
require 'keepachangelog'
parser = Keepachangelog::MarkdownParser.load('CHANGELOG.md')
puts parser.to_json
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.