Project

devist

0.01
No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
A Ruby gem that will help you export your Markdown changelog into beautiful HTML pages.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.3
~> 0.7
~> 12.0
 Project Readme

Gem Version Build Status Code Climate Dependency Status

devist!

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

Table of content

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

devist-term

How do I devist? (Getting started)

  • 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 :)

Installation

Requirements

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.

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 https://github.com/duraki/devist
$ cd devist && gem build devist
$ gem install ./devist

General

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

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

Integrations

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):

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

Git integration

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

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

Contribution

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.

License

Devist is released under the MIT License.

As seen on: