Skip to content

Latest commit

 

History

History
88 lines (54 loc) · 4.05 KB

using_the_pac_docker_image.md

File metadata and controls

88 lines (54 loc) · 4.05 KB
Raw

Using the PAC docker image

We supply a PAC docker image, praqma/pac, to easily run PAC and avoid any Ruby environment configuration.

Try it!

  1. Pull the image: docker pull praqma/pac
  2. Test-run the image: docker run --rm praqm/pac which when successful should output help and usage similar to this:
praqmatic automated changelog 

Usage:
  ./pac.rb (-d | --date) <to> [<from>] [options] [-v...] [-q...]
  ./pac.rb (-s | --sha) <to> [<from>] [options] [-v...] [-q...]
  ./pac.rb (-t | --tag) <to> [<from>] [options] [-v...] [-q...]
  ./pac.rb from <oldest-ref> [--to <newest-ref> | --to-date <newest-date>] [options] [-v...] [-q...] [-c (<user> <password> <target>)]... 
  ./pac.rb from-date <from_date> [--to <newest-ref> | --to-date <newest-date>] [options] [-v...] [-q...] [-c (<user> <password> <target>)]...
  ./pac.rb from-latest-tag <approximation> [--to <newest-ref> | --to-date <newest-date>] [options] [-v...] [-q...] [-c (<user> <password> <target>)]...
  ./pac.rb -h|--help


Options:
  -h --help  Show this screen.

  --from <oldest-ref>  Specify where to stop searching for commit. For git this takes anything that rev-parse accepts. Such as HEAD~3 / Git sha or tag name.

  --from-date <from-date>  Use dates to select the changesets.

  --from-latest-tag  Looks for the newest commit that the tag with <approximation> points to.  
    
  -d --date  Use dates to select the changesets.  

  -s --sha  Deprecated since 2.1.0. Use --from instead.
              
  --settings=<path>  Path to the settings file used. If nothing is specified default_settings.yml is used      

  --properties=<properties>  

    Allows you to pass in additional variables to the Liquid templates. Must be in JSON format. Namespaced under properties.* in 
    your Liquid templates. Referenced like so '{{properties.[your-variable]}}' in your templates.

    JSON keys and values should be wrapped in quotation marks '"' like so: --properties='{ "title":"PAC Changelog" }'      

  -v  More verbose output. Can be repeated to increase output verbosity or to cancel out -q

  -q  Less verbose output. Can be repeated for more silence or to cancel out -v

  -c  Override username and password. Example: `-c my_user my_password jira`. This will set username and password for task system jira.

Usage

With the PAC docker container, the basic usage examples in the README becomes:

	docker run --rm praqma/pac -h
docker run --rm -v $(pwd):/data -v $(pwd):/pac-templates praqma/pac --settings=/data/pac_settings.yml -t Release-1.0
	docker run --rm -v $(pwd):/data -v $(pwd):/pac-templates praqma/pac --settings=/data/pac_settings.yml -t Release-1.0 Release-2.0
docker run --rm -v $(pwd):/data -v $(pwd):/pac-templates praqma/pac --settings=/data/pac_settings.yml -d 2013-10-01

Try out a more elaborate example: Try PAC with a test repo and PAC docker image

Use it with a repository

  1. First write a file as outlined in the README
  2. Then create a template for the changelog report as outlined in the README

Then we can try to use PAC.

Assume we have our nice templates stored in our home directory under ~/pac-templates and each project (repository) have its own PAC configuration file in the root of the repository and named pac_settings.yml.

Then when we run the docker container we mount in the git repository together with the templates:

docker run --rm -v $(pwd):/data -v ~/pac-templates:/pac-templates --settings=/data/pac_settings.yml praqma/pac -d 2013-01-01

Running this command will produce a report that takes all commits from 2013 up till HEAD of the repository.

The relevant PAC configuration file matching the above needs templates defined as follows if we assume you've created a template ~/pac-templates/my-template.md:

  :templates:
    - { location: '/pac-templates/my-template.md', output: my-changelog.md }

That'll produce a my-changelog.md in the root of your your project.