changelog
Easily create, manage and maintain changelogs
Installation
This project can be used as both a command line application and as a module. A simple API is currently available that gives access to changelog functions as an npm module.
To install as a command line application, run the following:
$ npm install changelogapp -g
As an aside, if you have vim
set as your $EDITOR
, then make sure that in your ~/.vimrc
file you add the following line (to enable spellcheck and non-destructive line-wrapping):
" Enable spellcheck and wrap for changelog edit messages
autocmd VimEnter .UPDATE_EDITMSG setlocal spell linebreak wrap
Command line usage
Navigate to the directory that you wish to create and modify changelogs in.
$ changelog <command> [<args>]
Below are the commands that can be run from the command line:
Simple commands
Command | Description |
---|---|
help |
List the documentation |
init |
Initialize a blank CHANGELOG.md file in the current directory |
parse |
Parse the CHANGELOG.md file to JSON format |
status |
Print out changelog information, including the current version and a summary of the changes made |
Changelog commands
add
, change
, deprecate
, remove
, fix
, and secure
as arguments all serve the same
purpose of updating the Unreleased
section of the changelog with content (corresponding
to the keepachangelog categories).
It will open $EDITOR
, at which point you can enter the changes made prevalent to that category, separating each new item with a new line.
Version commands
Command | Description |
---|---|
bump [version \| patch \| minor \| major] |
This command will bump the Unreleased header to the next desired version. If no argument is specified a patch update will automatically be applied. You can specify your own version (provided it adheres to Semantic Versioning) or you can specify a patch, minor or major jump |
copy |
Copy the contents of the latest release item to the clipboard in markdown format |
API usage
First things first, install the module as normal by running the following command in the directory you want to install to:
$ npm install changelogapp
Currently you can parse
changelogs to JSON format and stringify
the result back into a CHANGELOG.md file.
Parsing a changelog
const changelog = ;const fs = ; // Get the CHANGELOG.md filefs;
For the above example, the output will be:
Stringify the JSON data back to markdown
const changelog = ;const fs = ;const parsedChangelog = ; // Stringify the JSONchangelog;
Given the JSON example from the previous section, the stringify
function will generate the following markdown file:
# Changelog 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). ## Unreleased ### Fixed - Remove the muffin man ## 0.0.1 - 2016-02-19 ### Added - The ability to do some cool stuff- Have you heard of the muffin man?
Warnings
Currently, changelog is very much in beta and a few things may not work perfectly. The most notable case being the fact that the parsing algorithm doesn't handle non-keepachangelog-style changelogs very well (if at all).
While support for changelogs that don't conform to this standard is not planned, if you have a CHANGELOG.md file that you believe should be supported, then create a new issue with the CHANGELOG.md file attached and a description of any errors you get.