conventional-commits-writer

    0.0.15 • Public • Published

    NPM version Build Status Dependency Status Coverage Status

    Write logs based on conventional commits and templates

    Install

    $ npm install --save conventional-commits-writer

    Usage

    var conventionalcommitsWriter = require('conventional-commits-writer');
     
    conventionalcommitsWriter(context, options);

    It returns a transform stream.

    It expects an object mode upstream that looks something like this:

    { hash: '9b1aff905b638aa274a5fc8f88662df446d374bd',
      header: 'feat(scope): broadcast $destroy event on scope destruction',
      type: 'feat',
      scope: 'scope',
      subject: 'broadcast $destroy event on scope destruction',
      body: null,
      footer: 'Closes #1',
      notes: [],
      references: [ { action: 'Closes', repository: null, issue: '1', raw: '#1' } ] }
    { hash: '13f31602f396bc269076ab4d389cfd8ca94b20ba',
      header: 'feat(ng-list): Allow custom separator',
      type: 'feat',
      scope: 'ng-list',
      subject: 'Allow custom separator',
      body: 'bla bla bla',
      footer: 'BREAKING CHANGE: some breaking change',
      notes: [ { title: 'BREAKING CHANGE', text: 'some breaking change' } ],
      references: [] }

    Each chunk should be a commit. Json object is also valid. Parts of the objects will be formatted and combined into a log based on the handlebars context, templates and options.

    The downstream might look something like this:

    <a name="0.0.1"></a>
    ## 0.0.1 "this is a title" (2015-05-29)
     
     
    ### Features
     
    * **ng-list:** Allow custom separator ([13f3160](https://github.com/a/b/commits/13f3160))
    * **scope:** broadcast $destroy event on scope destruction ([9b1aff9](https://github.com/a/b/commits/9b1aff9)), closes [#1](https://github.com/a/b/issues/1)
     
     
    ### BREAKING CHANGES
     
    * some breaking change

    API

    conventionalcommitsWriter([context, [options]])

    Returns a transform stream.

    context

    Variables that will be interpolated to the template. This object contains, but not limits to the following fields.

    version

    Type: string

    Version number of the up-coming release. If version is found in the last commit before generating logs, it will be overwritten.

    title

    Type: string

    isPatch

    Type: boolean Default: semver.patch(context.version) !== 0

    By default, this value is true if version's patch is 0.

    host

    Type: string

    The hosting website. Eg: 'https://github.com' or 'https://bitbucket.org'

    repository

    Type: string

    The repository name on host. Eg: 'stevemao/conventional-commits-writer'.

    linkReferences

    Type: boolean Default: true if host, repository, commit and issue are truthy

    Should all references be linked?

    commit

    Type: string Default: 'commits'

    Commit keyword in the url if options.linkReferences === true.

    issue

    Type: string Default: 'issues'

    Issue or pull request keyword in the url if options.linkReferences === true.

    date

    Type: string Default: dateFormat(new Date(), 'yyyy-mm-dd', true)

    Default to formatted ('yyyy-mm-dd') today's date. dateformat is used for formatting the date. If version is found in the last commit, committerDate will overwrite this.

    options

    Type: object

    transform

    Type: object or function Default: get the first 7 digits of hash, strip leading 'v' for version, and committerDate will be formatted as 'yyyy-mm-dd'.

    Replace with new values in each commit.

    If this is an object, the keys are paths to a nested object property. the values can be a string (static) and a function (dynamic) with the old value and path passed as arguments. This value is merged with your own transform object.

    If this is a function, the commit chunk will be passed as the argument and the returned value would be the new commit object. This is a handy function if you can't provide a transform stream as an upstream of this one. If returns a falsy value this commit is ignored.

    a raw object that is originally poured form upstream is attached to commit.

    groupBy

    Type: string Default: 'type'

    How to group the commits. EG: based on the same type. If this value is falsy, commits are not grouped.

    commitGroupsSort

    Type: function, string or array Default: 'title'

    A compare function used to sort commit groups. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.

    The string can be a dot path to a nested object property.

    commitsSort

    Type: function, string or array Default: 'header'

    A compare function used to sort commits. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.

    The string can be a dot path to a nested object property.

    noteGroupsSort

    Type : function Default: 'title'

    A compare function used to sort note groups. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.

    The string can be a dot path to a nested object property.

    notesSort

    Type: function Default: sort by localeCompare.

    A compare function used to sort note groups. If it's a string or array, it sorts on the property(ies) by localeCompare. Will not sort if this is a falsy value.

    The string can be a dot path to a nested object property.

    generateOn

    Type: function or string Default: if commit.version is a valid semver.

    When the upstream finishes pouring the commits it will generate a block of logs by default. However, you can generate more than one block based on this criteria (usually a version) even if there are still commits from the upstream. NOTE: It checks on the transformed commit chunk instead of the original one (you can check on the original by access the raw object on the commit). However, if the transformed commit is ignored it falls back to the original commit.

    reverse

    Type: boolean Default: false

    Are the commits from upstream in the reverse order? You should only worry about this when generating more than one blocks of logs based on generateOn. If you find the last commit is in the wrong block inverse this value.

    includeDetails

    Type: boolean Default: false

    If this value is true, instead of emitting strings of changelog, it emits objects containing the details the block.

    mainTemplate

    Type: string Default: template.hbs

    The main handlebars template.

    headerPartial

    Type: string Default: header.hbs

    commitPartial

    Type: string Default: commit.hbs

    footerPartial

    Type: string Default: footer.hbs

    partials

    Type: object

    Partials that used in the main template, if any. The key should be the partial name and the value should be handlebars template strings. If you are using handlebars template files, read files by yourself.

    Customization Guide

    It is possible to customize this the changelog to suit your needs. Templates are written in handlebars. You can customize all partials or the whole template. Template variables are from either upstream or context. The following are a suggested way of defining variables.

    upstream

    Variables in upstream are commit specific and should be used per commit. Eg: commit date and commit username. You can think of them as "local" or "isolate" variables. A "raw" commit message (original commit poured from upstream) is attached to commit.

    context

    context should be module specific and can be used across the whole log. Thus these variables should not be related to any single commit and should be generic information of the module or all commits. Eg: repository url and author names, etc. You can think of them as "global" or "root" variables.

    Basically you can make your own templates and define all your template variables. This module can iterate the commits and compile them. For more details, please checkout handlebars and the source code of this module.

    CLI

    $ npm install --global conventional-commits-writer
    $ conventional-commits-writer --help
     
      Write logs based on conventional commits and templates
     
      Usage
        conventional-commits-writer <path> [<path> ...]
        cat <path> | conventional-commits-writer
     
      Example
        conventional-commits-writer commits.ldjson
        cat commits.ldjson | conventional-commits-writer
     
      Options
        -c, --context    A filepath of a json that is used to define template variables
        -o, --options    A filepath of a javascript object that is used to define options

    It works with Line Delimited JSON.

    If you have commits.ldjson

    {"hash":"9b1aff905b638aa274a5fc8f88662df446d374bd","header":"feat(ngMessages): provide support for dynamic message resolution","type":"feat","scope":"ngMessages","subject":"provide support for dynamic message resolution","body":"Prior to this fix it was impossible to apply a binding to a the ngMessage directive to represent the name of the error.","footer":"BREAKING CHANGE: The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.\nCloses #10036\nCloses #9338","notes":[{"title":"BREAKING CHANGE","text":"The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive."}],"references":[{"action":"Closes","repository":null,"issue":"10036","raw":"#10036"},{"action":"Closes","repository":null,"issue":"9338","raw":"#9338"}]}

    And you run

    $ conventional-commits-writer commits.ldjson -o options.js

    The output might look something like this

    <a name="1.0.0"></a>
    # 1.0.0 (2015-04-09)
     
     
    ### Features
     
    * **ngMessages:** provide support for dynamic message resolution 9b1aff9, closes #10036 #9338
     
     
    ### BREAKING CHANGES
     
    * The `ngMessagesInclude` attribute is now its own directive and that must be placed as a **child** element within the element with the ngMessages directive.

    It is printed to stdout.

    License

    MIT © Steve Mao

    Install

    npm i conventional-commits-writer

    DownloadsWeekly Downloads

    7

    Version

    0.0.15

    License

    MIT

    Last publish

    Collaborators

    • stevemao