A Ruby gem to help you: keep proper changelog for your pojects. - https://devist.io
- You are a developer with a typical
changelog.mdfile 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 hereBasic requirements for the changelog.md file are these:
- There are optional
@project,@author, and@homepagereferences. - 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-pushOnce 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.