Sheep a changelog
:sheep: Simple, particular, example driven parser of keep-a-changelog format.
About
Parse a markdown changelog in keep-a-changelog format to the optimal resolution depth to perform semantic tasks.
Install
See RubyGems for installation instructions (simply add to your Gemfile).
Sheep-a-changelog requires at least ruby 2.2, and is tested on several minor versions up to 2.5.
Getting started
require 'sheep-a-changelog'
# Load keep-a-changelog markdown file as a string
contents = File.read('./path/to/CHANGELOG.md')
# Create an abstraction for it using the parser
# SheepAChangelog.parse: string -> SheepAChangelog.Node
doc = SheepAChangelog.parse(contents)
# TODO temper with the structure
# See features section
# Serialize back to string
updated = doc.to_s
# Save back
File.write('./path/to/CHANGELOG.md', updated)
Features
Release
This method performs the following actions:
- Rename current unreleased version log to new version
- Add anchor for new version
- Add empty unreleased
- Update unreleased anchor
It accepts arguments
new_version
- semver formattag_prefix
- prefix fornew_version
for git tags (used for anchors). Defaults tov
date
- date of the release, defaults to now
doc.release('2.0.0', 'v', Time.utc(2017, 6, 20))
Inspect element
node.build_tree
# :title - heading (string) or :empty for top-level node
# :lines - string[] of contents belonging to this node, without anchors and child nodes
# :anchors - { :v, :url } of anchor nodes
# :nodes - child nodes
:title: :empty
:lines: []
:anchors:
- :v: Unreleased
:url: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
- :v: 1.0.0
:url: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
:nodes:
- :title: Changelog
:lines:
- All notable changes to this project will be documented in this file.
- ''
- The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
- and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
- ''
:anchors: []
:nodes:
- :title: "[1.0.0] - 2017-06-20"
:lines: []
:anchors: []
:nodes:
- :title: Added
:lines:
- '- "Frequently Asked Questions" section.'
- ''
:anchors: []
:nodes: []
Latest version title
Returns the contents of the heading for the latest version.
doc.latest_version_title
# --> "[1.0.0] - 2017-06-20"
Diff prefix
Returns URL prefix for the anchors. If multiple used, return the most frequent.
doc.diff_prefix
# --> "https://github.com/olivierlacan/keep-a-changelog/compare/"
Rename version
Rename version. Looking for exact match. This only changes the title and keeps the contents (inlcuding all children intact.)
doc.rename_version('[Unreleased]', new_version)
Add anchor
doc.add_anchor('LABEL', 'vFROM', 'vTO')
# adds "[LABEL]: {diff_prefix}/vFROM...vTO" as the topmost anchor
Todo
- :heavy_check_mark: Ensure unreleased
- :heavy_check_mark: Release
- :construction: Initialize
- :construction: Sort type sections
- :construction: Fix typos in type sections
License
Licensed under MIT