Changelog for developers
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Gem Version Build Status Code Climate Dependency Status


A Ruby gem to help you: keep proper changelog for your pojects. -

Table of content


How do I devist? (Getting started)

  • You are a developer with a typical file in your project.

devist, helps you to:

  • keep your logfile clean and readable,
  • export these file to *.html,
  • integrated in git and deployment,
  • offer number of other features ...

Install Devist through Gem:

$ gem install devist

$ (cd ~/project)
$ devist init && devist changelog
         __          _      __ 
    ____/ /__ _   __(_)____/ /_
   / __  / _ \ | / / / ___/ __/
  / /_/ /  __/ |/ / (__  ) /_  
- Release notes generator.

  Use --help for details.

  * devist will try to generate export for file 'changelog' with theme 'default'
  * File '' exists; continuing ...
  * Theme '_default.html.erb' exists; continuing ...
  * Checking if changelog is devist configured ...
  * Found .devist signature.
  * Building model from file data ...
  * Extracting project name ... [devist]
  * Extracting project author ... [Halis Duraki <>]
  * Extracting project homepage ... []
  * Found version 1.0.0; registered ...
  * Trying to compile set ...
  * Creating new export from erb ...
  * Injecting parsed results to the erb ...
  * Writing compiled data to changelog file ...
  ** All done! Check changelog.html file in your browser :)



Since devist is built natively with Ruby components/libs, you can start using devist right now.

Check if your system does have at least Ruby 2.0.0 installed.

$ ruby -v
ruby 2.0.0p648 (.) 

$ gem --version
2.6.0 >

Of course, your project should have or equivalent so devist can parse and export something.

Automatic Installation

To install devist, run:

$ gem install devist

Manual Installation

For nightly builts, you may want to clone or checkout the branch and build the gem from .*gemspec.

$ git clone
$ cd devist && gem build devist
$ gem install ./devist


Demo is available at devist changelog. The devist is built and debugged upon it's changelog file. Ain't that cool?

Changelog format

The changelog format we prefer is really easy to remember and understand under various circumstances. Generate a new changelog skeleton using command line.

$ devist init
* Generating ...
* Output .devist as a way of thinkering ...
** All done! Continue editing

$ cat
### Version 1.0.0 of 20 Jul 2017
+ #added: something goes here

Basic requirements for the file are these:

  • There are optional @project, @author, and @homepage references.
  • To register a version, use ### Version x.x(.x) of Mon(th) dd YYYY.
  • To register a change, use + #[tag]: (change).

Why is it useful?

  • Markdown parse
  • Static output, HTML with theme support
  • Different changelog format support
  • Easy to use and zero dependencies
  • Extensible
  • Enjoy proper changelog

Themes (+ contribution)

Refer to default themes in repository for contribution help and future documentation.

Easiest way to create theme is to bundle it in one static page, although you can extend it how ever you want.

Download themes to your $HOME/.devist-themes/ or call devist theme [raw] where ever you want.

# Install manually

$ mkdir $HOME/.devist-themes
$ cd $HOME/.devist-themes
$ wget
# Install using devist bin

$ devist theme default

** Installing Devist theme to `$HOME/.devist-themes/` ...

The compiler build themes upon *.erb binding.

If you want to contribute to themes, please, do so in devist-themes repository. To learn how to make own themes, please refer to our API. For better understanding, read the code of built-in themes.

Here is small list of contribution guidelines regarding public themes:

  • Your theme should do only one thing - show changelog / release notes
  • If you want to publish the theme for public in our repository, that is awesome!
  • Theme authors are allowed. Props.
  • The theme should follow the in-line and in-file style (no external stylesheets / JS / ads / tracking are allowed)
  • Google Fonts is allowed


Deploy integration

One can use devist command on his pre-deploy stage to generate changelog on release. Example is presented below (pseudo on Mage configuration):

   - hostname
   - devist changelog
   - mv changelog.html {your-app}/public/views/

Git integration

As of Devist v1.1.4, you can integrate a Git hook, located in file in this repository. The only thing you have to do is copy this file to your repository hooks. Example follows as below.

# Integrate git-push hook
$ cd dev/your-project
$ cd .git/hooks/ && wget 
$ mv pre-push && chmod +x pre-push

Once this git hook is added to your repository, you can't push a tag or release until you properly bumped the changelog version. To do so, the script goes through the file before pushing the remote release, and check for a valid version. If current tag can't be located in that file, the script exit with error code registered by git and aborted.


$ (repo) $ git tag v2.1.1
$ (repo) $ git push origin v2.1.1
Devist / tag/hook / pre-push -
> Pre-push hook activated.
> Tag detected.
> Checking for file in this directory ...
Checking tag version ...
Stripping non-numeric characters ...
Detected tag: 2.1.1
Checking latest TAG in changelog file ...
Tag not found in ; please bump your version.
Use --no-verify while to skip this git-hook.

This is perfect solution if you don't want to push release without changelog bump. So, for above to works correctly, edit your logfile.

One can change default filename to whatever his logfile name is. Make sure to only edit LOGFILE variable inside the bash script.

In case you really don't care if file consist of HEAD tag, you can use --no-verify to skip the hook.


$ git tag v1.0.0
$ git push origin v1.0.0 --no-verify


API is documented at rubydoc. Refer to project wiki for some more documentation.


All contribution on devist project, devist themes, or overall code or documentation in general is highly appreciated. Please refer to CONTRIBUTION file for more details.


Devist is released under the MIT License.

As seen on: