chan

Chan is a likeable CLI tool used for writing and maintaining a CHANGELOG empowering the user to use a coloquial/friendly style. See more here: keepachangelog.com

Sections
Getting started
Usage
CLI
Configuration
Plugins
API
- chan
- cli
- parser
Issues
Contribute

Getting started

Install:

$ npm install -g @geut/chan

Usage

CLI

Create a CHANGELOG.md file in your project root folder with:

$ chan init

To add entries to your CHANGELOG use the command that describes better your change (added, changed, fixed, etc)

$ chan added "Added `foo` in API to print foo in the console."

This command will modify your CHANGELOG creating a new entry called added under the Unreleased section.

chan follows the keepachangelog.com format/style.

Using your own editor

In case you want to use an editor you can just omit the message parameter:

$ chan added # this will open your $EDITOR

available commands:

init Creates a CHANGELOG.md if it does not exists. Chan will work with this file.
- -o, --overwrite overwrite the current CHANGELOG.md [boolean]
added [msg] Writes your changelog indicating new stuff.
fixed [msg] Writes your changelog indicating fixed stuff.
changed [msg] Writes your changelog indicating updated stuff.
security [msg] Writes your changelog indicating security upgrades.
removed [msg] Writes your changelog indicating removed stuff.
deprecated [msg] Writes your changelog indicating deprecated stuff.
release <semver> Groups all your new features and marks a new release on your CHANGELOG.md.
- --git-compare Overwrite the git compare by default [string]

options:

-p, --path Define the path of the CHANGELOG.md (cwd by default) [string]
--stdout Define the output as STDOUT [boolean]
--silence Disable the console messages [boolean]
-u, --use Extend chan with your own commands [array] [default: []]
--config Path to your JSON config file [string]
-h, --help Show help [boolean]
-v, --version Show version number [boolean]

Notes:

[OPTIONAL]

<REQUIRED>

Configuration

You can use a config JSON file or your package.json to set a static configuration (global arguments, command arguments and plugins).

config.json

{
    "global-argv": [
        "stdout": true
    ],
    "command-argv": [
        "init": {
           "overwrite": true
        }
    ]
}

$ chan --config=./config.json

package.json

{
    "chan": {
        "global-argv": [
            "stdout": true
        ],
        "command-argv": [
            "init": {
               "overwrite": true
            }
        ]
    }
}

Plugins

You can extend chan quite easily by adding your own commands as plugins.

chan-command-hello.js

module.exports = function () {
    return {
        command: 'hello <name>',
        describe: 'A command that say hello',
        handler: function (parser, argv, write) {
            this.log().info('hello ' + argv.name);
        }
    }
}

You can consume local commands by using a local path (e.g.: ./chan-command-hello.js) or you can pick a name prefixed by "chan-command-" if the command is available on NPM.

New commands can be added by three different ways.

Using the argument --use:

$ chan hello 'geut' --use=chan-command-hello
$ hello geut

Using --config pointing to a json file:

config.json

{
    "use": [
        "chan-command-hello"
    ]
}

$ chan hello 'geut' --config=./config.json
$ hello geut

Using the package.json:

package.json

{
    "chan": {
        "use": [
            "chan-command-hello"
        ]
    }
}

$ chan hello 'geut'
$ hello geut

API

Chan is created above two excellent projects. We use yargs for the CLI and remark to parse the CHANGELOG.md

import chan, { cli, parser } from '@geut/chan';

chan

chan exposes the main api:

init({ overwrite = false, cwd }): The init method will create a CHANGELOG.md file in cwd directory.
- overwrite {Boolean}: True to overwrite an exisiting CHANGELOG file. Default to false.
- cwd {String}: The directory to create the CHANGELOG. If not provided the process.cwd() is used.
change({ type, msg, cwd }): Adds the message msg as part of the section type.
- type {String}: One of the chan.CHANGE_TYPE
- msg {String}: The message text to be added.
- cwd {String}: The directory of CHANGELOG. If not provided the process.cwd() is used.
CHANGE_TYPE
- ADDED
- CHANGED
- FIXED
- SECURITY
- DEPRECATED
- REMOVED
release({ version, cwd }): Generates a new release section. Moves the current Unrelasead changes list to the provided version.
- version {String}: The version number.
- cwd {String}: The directory of CHANGELOG. If not provided the process.cwd() is used.

cli

cli retruns a command line interface instance.

run(): Executes the cli.
yargs(): Returns the yargs instance.

parser

The parser is a wrapper instance of an excellent project called remark.

To instantiate a parser supply the working directory where the CHANGELOG file is located:

import { parser } from '@geut/chan';

//....

const myParser = parser(cwd);

If cwd is not passed, the process.cwd() is used.

The parser instance exposes the following methods and properties:

remark: The remark instance.
exists(): Returns true if the CHANGELOG file exists.
write(content): Writes the content to the CHANGELOG file.
- content {String}: If not supplied, the remark.stringify content.
findRelease(version): Returns the sub-tree corresponding to the provided version.
- version {String}: Release version.
getMTREE(): Returns the CHANGELOG representation.

Internally, chan maintains its own CHANGELOG representation using a simple tree structure which looks like this:

{
    releases: [{
        text: '## [Unreleased]',
        start: Number,
        len: Number,
        children: [{
            text: 'Added',
            children: [{
                text: 'some new feature'
            }, {
                text: 'other feature'
            }]
        }]
    }, {
        text: '## [0.3.0] - 2015-12-03',
        start: Number,
        len: Number,
        children: [Object]
    }],
    definitions: {
        start: Number,
        children: [{
            text: '[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...HEAD'
        }]
    }
}

ISSUES

🐛 If you found an issue we encourage you to report it on github. Please specify your OS and the actions to reproduce it.

CONTRIBUTE

👥 Ideas and contributions to the project are welcome. You must follow this guideline.

A GEUT project

estebanprimost/chan

chan

Table of contents

Getting started

Usage

CLI

Using your own editor

available commands:

options:

Configuration

Plugins

API

chan

cli

parser

ISSUES

CONTRIBUTE