devist!

A Ruby gem to help you: keep proper changelog for your pojects. - https://devist.io

• Getting started
• Installation
  • Requirements
  • Gem / Automatic
  • Manual
• General
  • Changelog format
  • Why is it useful
  • Themes
• Integrations
  • Deploy integration
  • Git integration
• API
• Contribution
• License

• You are a developer with a typical changelog.md 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.
  https://github.com/duraki/devist

  Use --help for details.

  * devist will try to generate export for file 'changelog' with theme 'default'
  * File 'changelog.md' 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 <duraki.halis@nsoft.ba>]
  * Extracting project homepage ... [https://devist.io]
  * 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 changelog.md or equivalent so devist can parse and export something.

To install devist, run:

$ gem install devist

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

$ git clone https://github.com/duraki/devist
$ 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?

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
--snip
* Generating CHANGELOG.md ...
* Output .devist as a way of thinkering ...
-
** All done! Continue editing CHANGELOG.md.

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

Basic requirements for the changelog.md 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).

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

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 https://raw.githubusercontent.com/duraki/devist/master/lib/devist/export/html/_default.html.erb

# Install using devist bin

$ devist theme default https://raw.githubusercontent.com/duraki/devist/master/lib/devist/export/html/_default.html.erb

** 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

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

deploy:
  dev:
   - hostname
  pre-deploy:
   - devist changelog
   ...
  post-deploy:
   - mv changelog.html {your-app}/public/views/

As of Devist v1.1.4, you can integrate a Git hook, located in hook.sh 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 https://raw.githubusercontent.com/duraki/devist/master/hook.sh 
$ mv hook.sh 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 CHANGELOG.md 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.

Example:

$ (repo) $ git tag v2.1.1
$ (repo) $ git push origin v2.1.1
Devist / tag/hook / pre-push - https://devist.io
> Pre-push hook activated.
> Tag detected.
> Checking for file CHANGELOG.md 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 CHANGELOG.md ; 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 CHANGELOG.md 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 CHANGELOG.md file consist of HEAD tag, you can use --no-verify to skip the hook.

Example:

$ 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.

• Rubygems.org
• Bestgems.org
• Versioneye.com
• API Rubydoc.info