Logchange

Logchange is an alternative approach to managing a changelog. Instead of writing to a flat CHANGELOG(.md), it logs changes to .yaml files containing a timestamp and a title. You can extend this format by adding any number of additional fields by specifying a template - allowing customization of the changelog to suit your needs.

Logchange allows you to release changes; this allows you to group changes into versioned releases, or timed releases, depending on what your project needs. New entries are kept in changelog/unreleased until the release command is used to append it to changelog/YEAR.yaml file.

This repository's changelog is maintained using logchange. See the automatically generated changelog/2017.yaml. Unreleased changes (if any) go to changelog/unreleased.

It's good to let your users know what you're up to, and it's good to keep track of what changed over time. If your project's code isn't public, it might make sense to include a private flag in your template and use that to show only a select list of changes to your users and the public. The YAML format allows the changelog to be extended to fit your specific requirements. It also makes it easy to parse and present the data on the front-end.

Add to your Gemfile:

gem 'logchange', '~> 1.0'

And then:

$ bundle install

Or install the gem with:

$ gem install logchange

$ logchange
Usage: logchange COMMAND

Available commands:
  init          - Initialize logchange at this location - creates
                  the changelog directory.
  new [MESSAGE] - Log a change. Skip the message to trigger
                  interative mode.
  release [TAG] - Releases changes in changelog/unreleased.
                  Optionally, tag the release with a string.

If you've just completed work on a feature, log it with:

$ logchange new "A cool new feature has been added"
Created [..]/changelog/unreleased/20170521-a-cool-new-feature-has-been-added.yml

This will create a new timestamped .yaml file in the changelog/unreleased folder.

timestamp: 2017-05-21T06:45:08Z
title: The title for your change goes here.

To extend the default template used, create changelog/template.yaml. See customization instructions below.

To release all new public changes to the flat file, run:

$ logchange release [TAG]

This will add all unreleased changes to changelog/YEAR.yaml. The current set of changes will be grouped together, and the time of release will be recorded. You can optionally specify a tag such as a version number. For example:

$ logchange release v0.1.1

This will group current set of changes and add a tag key along with the release timestamp.

Create a changelog/template.yaml file to add additional keys for information that you'd like to track in your project.

# There will two keys by default - timestamp and title.
# You can add any number of additional keys - this depends on your workflow.
# A few examples are below.

description: Add more detailed information about the change?
github_issue_link: Add link to related Github issue.
private: Hide this change from the public? Set to true or false.

If the template is customized, you can use Logchange's interactive mode to supply required data, instead of passing it directly via the command:

$ logchange new
title: A cool new feature has been added.

github_issue_link: Add link to related Github issue.
https://github.com/harigopal/logchange/issues/1

private: Hide this change from the public? Set to true or false.
false

Created [..]/changelog/unreleased/20170521-a-cool-new-feature-has-been-added.yml

After checking out the repo, run bundle install to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/harigopal/logchange.

The gem is available as open source under the terms of the MIT License.