stringify-changelog

Generate a markdown-formatted changelog from an object, array, yaml or json file.

Converts valid YAML, like this:

v0.1.0:
  date: "2016-12-26"
  changed:
    - Got stuck in another chimney.

Into this:

### [v0.1.0] - 2016-12-26
 
**changes**
 
- Got stuck in another chimney.

Install

Install with npm:

$ npm install --save stringify-changelog

Usage

var changelog = require('stringify-changelog');
changelog(value, options);

Params

value {String|Object|Array}: File path of YAML file to read, object or array of changes (see below)
options {Object}: the following options may be passed to modify output
- format {Function} Custom function for formatting each entry in the changelog
- key {Function} Prepend the following key/reference to your generated changelog, to guide users in making semantically labeled entries.

Example key

## key

Changelog entries are classified using the following labels from [keep-a-changelog][]:

- `added`: for new features
- `changed`: for changes in existing functionality
- `deprecated`: for once-stable features removed in upcoming releases
- `removed`: for deprecated features removed in this release
- `fixed`: for any bug fixes

[keep-a-changelog]: https://github.com/olivierlacan/keep-a-changelog

Data format

Conventions from [keep-a-changelog][] are supported by default. When data is passed as an object or array (from a file or directly), changelog entries can be categorized using the following labels as property names:

added for new features.
changed for changes in existing functionality.
deprecated for once-stable features removed in upcoming releases.
removed for deprecated features removed in this release.
fixed for any bug fixes.
security to invite users to upgrade in case of vulnerabilities.

Examples

Data can either be formatted as an array or an object.

Object

JSON

{ 'v0.1.0':
   { date: '2016-12-26',
     changed: [ 'Got stuck in another chimney.' ] } }

YAML

v0.1.0:
  date: "2016-12-26"
  changed:
    - Got stuck in another chimney.

Array

JSON

[ { date: '2016-12-26',
    version: 'v0.1.0',
    changed: [ 'Got stuck in another chimney.' ] } ]

YAML

- version: v0.1.0
  date: '2016-12-26'
  changed:
    - Got stuck in another chimney.

Arbitrary entries

If you don't want to follow keep-a-changelog format, or you have an arbitrary entry that doesn't fit in one of the above categories, you can use the description property.

Array

[ { date: '2016-12-26',
    version: 'v0.1.0',
    description: [ 'Got stuck in another chimney.' ] } ]

Object

{ 'v0.1.0':
   { date: '2016-12-26',
     description: [ 'Got stuck in another chimney.' ] } }

About

Related projects

helper-changelog: Template helper for generating a markdown-formatted changelog from an object, array or yaml file. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

License

This file was generated by verb, v0.9.0, on July 21, 2016.