prepare to make gargamel public

- gpl3 licence
- touch up readme
   - documenting gargamel.edn
   - documenting expected placeholders in templates

README.md

@@ -10,6 +10,11 @@ There are two interfaces for gargamel: either use the lein plugin for clojure pr
 
 Note that currently gargamel expects release tags in the following format: `release-buildnumber-date_time` matching the pattern `release-\d+-\d+_\d+`.
 
+### Prerequisites
+
+java runtime environment: basically `java -jar` should work.
+
+Gargamel also does not handle login/auth to github/bitbucket it just shells out so the shell gargamel runs in should be 'authenticated' to access the git repos you want to work with.
 
 ### Leiningen plugin
 
@@ -39,9 +44,26 @@ Or to generate the latest releaase notes changelog between the two latest releaa
 
     $ gargamel.sh -v -r -p clj_fe -d /tmp/
 
+## Project specific config file
+
+Gargamel looks for a file named `gargamel.edn` in the project's directory. This file should be in [edn format](https://github.com/edn-format/edn).
+
+Please see example config files:
+- [config file](gargamel.edn) for markdown output, please see **comments** in this file explaining the config file format
+- [config file](gargamel-html.edn) for html output
+
+## Change log templates
+
+[Mustache](http://mustache.github.io/) templates are used to generate changelog or release notes with Gargamel. Plase see example mustache templates
+- for [html output](resources),
+- for [markdown output](md-templates).
+
+You can use your own custom templates by providing a path to a directory in `gargamel.edn` config file using the `:template-dir` key. Gargamel expects a `changelog.mustache` file as the main template: it can then include other mustache templates mustache style: `{{> other_template}}.
+
+Please see expected placeholders in the html output template files [here](resources).
+
 ## License
 
-Copyright © 2014 FIXME
+Copyright © 2014 MailOnline
 
-Distributed under the Eclipse Public License either version 1.0 or (at
-your option) any later version.
+Distributed under the [GNU General Public License, version 3](http://opensource.org/licenses/GPL-3.0)

gargamel.edn

@@ -8,7 +8,7 @@
  [{:key :fixes :regex ".*#\\d+.*" :title "New features, bugfixes"}
   {:key :wip :regex ".*\\[[Ww][iI][pP]\\].*" :title  "Work in progress, not yet ready"}]
  :formattable-objects
- ;; defines custom transformations on text chunks, can be used for links in the changelog (commit hashes are turned into links automatically)
+ ;; defines custom transformations on text chunks, can be used for links in the changelog (commit hashes are turned into links automatically) for example
  ;; template: the template fragment to use
  ;; regex: to select bits of text to be transformed
  ;;

resources/changelog.mustache

@@ -29,3 +29,12 @@
 	{{/sections}}
   </body>
 </html>
+{{!
+- to: git ref
+- to-url: generated url pointing to the 'to' git ref
+- from: git ref
+- from-url: generated url pointing to the 'from' git ref
+- compare-url: generated url pointing at github compare page between 'from' and 'to' ref
+- title: title of section
+- commits: list of commits
+}}

resources/commit.mustache

@@ -1,3 +1,14 @@
 <li><a href="{{url}}">{{hash}}</a> (<em>{{project-name}}</em>) {{date}} [{{commiter}}]  <strong>{{{linked-subject}}}</strong>
 <p>{{{linked-body}}}
 </li>
+{{!
+- hash: commit hash
+- url: genearted commit url
+- project-name: name of the project (useful if you are using bower components)
+- date: date of the commit
+- commiter: commiter
+- subject: subject line of commit message
+- linked-subject: subject with formattable objects processed
+- body: body of the commit message
+- linked-body: body with formattable objects processed
+}}