Need Package Maintenance

    grunt-templated-changelog

    0.1.3 • Public • Published

    grunt-templated-changelog

    Generates customized changelog file from git logs.

    Getting Started

    This plugin requires Grunt ~0.4.2

    If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

    npm install grunt-templated-changelog --save-dev

    Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

    grunt.loadNpmTasks('grunt-templated-changelog');

    The "changelog" task

    Overview

    This plugin is inspired by conventional-changelog the goal was to allow custom commit conventions and output formatting.

    The bare minimum needed to get task running is to define options as following

    chagelog: {
      release: {
        options: {
          version: '0.1.0'
        }
      }
    }
    

    which would prepend generated changelog to your CHANGES.md by default

    # 0.1.0
    
    - Fixing Something somehow `021e25c`
    - Another fix `fade3f6`
    - Added tweaks and tricks `2ead19e`
    - Another commit `6048f34`
    - multiline comment `dddc845`
    - One line comment with no label `bf4394b`
    

    Task grabs Git log records since the most recent tag or first commit if no tags were made yet. Format and content can be heavily customized by passing different options.

    Usage Examples

    Simple use not requirung any commit format conventions

    chagelog: {
      release: {
        options: {
          version: '0.1.0'
        }
      }
    }
    

    Compact changelog including only maeningfull commits. Assuming you add label(target) marker at the beginning of commit message and separate subject from commit body with empty line

    chagelog: {
      release: {
        options: {
          version: '0.1.0',
          labels: ['feature', 'bugfix'],
          template: 'labeled'
        }
      }
    }
    

    If you have many people using your code and want to expose maximum of information try this

    chagelog: {
      release: {
        options: {
          version: '0.1.0',
          labels: ['feature', 'bugfix'],
          template: 'grouped'
        }
      }
    }
    

    And you always can use your own format convention and handle it with custom options.matchers and optoins.template.

    Options

    options.version

    Type: String Default value: next

    A string value defining the version headline

    options.changelog

    Type: String Default value: CHANGES.md

    Path to the changelog file

    options.write

    Type: Boolean Default value: true

    Tells either generated log should be written to the file. You may set it to false or run the task with --no-write to preview the content.

    options.branch

    Type: String Default value: null

    Requires the task to be ran in specific branch if needed.

    options.labels

    Type: String[] Default value: []

    Tells the task to only grab commits with specific labels and list them in corresponding order. This helps to keep only meaningful information in the changelog. By default Commits are labeled by adding label[target] string at the beginning of the commit message. conventional-changelog makes a good suggestion on label names to be used

    • feat A new feature
    • fix A bug fix
    • docs Documentation only changes
    • style Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
    • refactor A code change that neither fixes a bug or adds a feature
    • test Adding missing tests
    • chore Changes to the build process or auxiliary tools and libraries such as documentation generation

    This list is just illustratin approach, it's up to you how to label commits.

    target should point you to the component changes relates to.

    Commit marker can be omited or customized with options.matchers

    options.template

    Type: String|Object Default value: simple

    There is few predefined templates you can refer by name simple, labeled, grouped. They are different by how much information they render.

    simple template

    # next
    
    - Fixing Something somehow `021e25c`
    - Another fix `fade3f6`
    - Added tweaks and tricks `2ead19e`
    - Another commit `6048f34`
    - multiline comment `dddc845`
    - One line comment with no label `bf4394b`
    

    labeled template

    # next
    
    - `bugfix` Fixing Something somehow `021e25c`
    - `bugfix` Another fix `fade3f6`
    - `feature` Added tweaks and tricks `2ead19e`
    - `refactor` multiline comment `dddc845`
    - `style` Another commit `6048f34`
    - One line comment with no label `bf4394b`
    

    grouped template

    # next
    
    ## feature
    ### Something
    - Added tweaks and tricks `2ead19e`
    
    ## bugfix
    ### Component
    - Another fix `fade3f6`
    
    ### Something
    - Fixing Something somehow `021e25c`
    
    ## style
    ### Component
    - Another commit `6048f34`
    
    
    ## Breaking changes
    
    - breaks the build
    - causes headaches
    
    Use `options.b` instead of `options.a`
    

    Also you can use custom template by setting options.template to file path relative to Gruntfile.

    In case you want to pass more data to the template or change existing you can do following:

    template: {
      file: 'path/to/file',
      data: {
        var1: value,
        var2: value
      }
    }
    

    or

    template: {
      file: 'path/to/file',
      data: function(data) {
        data.var1 = value;
        data.var2 = value;
        return data;
      }
    }
    

    options.matchers

    Type: String Default value: {}

    Use this option if you need to grab bits of data from commit message. Lets say you have following in commits @marker:value. To make commit.marker available in templates you need

    matchers: {
      marker: /@marker:(\w+)/
    }
    

    first memorized group in RegExp is becoming a value. For more advannced logic you can use function values

    matchers: {
      marker: function(body) {
        return body.match(/@marker:(\w+)/)[1];
      }
    }
    

    There some some predefine matchers which you can override if needed: subject, label, target, breaking_changes.

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    See CHANGES.md

    Install

    npm i grunt-templated-changelog

    DownloadsWeekly Downloads

    1

    Version

    0.1.3

    License

    none

    Last publish

    Collaborators

    • yavorskiys