diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..566be7a --- /dev/null +++ b/.dockerignore @@ -0,0 +1 @@ +reports \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9b35082..f1b4a33 100644 --- a/.gitignore +++ b/.gitignore @@ -3,10 +3,8 @@ changelog.md changelog.pdf changelog.html -pac coverage test/reports -test/resources/stop_task_system* default.html default.md default_ids.md @@ -14,4 +12,4 @@ default.pdf default-generated.* .bundle .idea/ -demorepo +*.gem diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e16682b..2ff6454 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ See [/docs/versioning.md](/docs/versioning.md) Product owners: -* Bue Petersen (Github handle: @buep) +* Mads Nielsen (Github handle: @MadsNielsen) * Peers: Jan Krag (Github handle: @JKrag), Claus Schneider (Github handle: @bicschneider) _Product owners_ will take the daily responsibility for any change: @@ -45,4 +45,4 @@ The _concept owners_ have the overall vision and make decisions on roadmap level Concept owner: -* Bue Petersen +* Mads Nielsen diff --git a/Dockerfile b/Dockerfile index 9f7c423..c983bcc 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,55 +1,21 @@ -FROM ruby:2.4 +FROM ruby:2.5.5 RUN apt-get update && \ apt-get install -y cmake && \ - apt-get install -y libxslt-dev && \ - apt-get install -y libxml2-dev && \ - rm -rf /var/lib/apt/lists/* - -RUN apt-get update && \ apt-get install -y locales && \ - rm -rf /var/lib/apt/lists/* - -#Set the locale -RUN sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \ - echo 'LANG="en_US.UTF-8"'>/etc/default/locale && \ - dpkg-reconfigure --frontend=noninteractive locales && \ - update-locale LANG=en_US.UTF-8 - -ENV LANG en_US.UTF-8 -ENV LANGUAGE en_US:en -ENV LC_ALL en_US.UTF-8 - -#This istalls a patched version of wkhtmltopdf that allows it to run headless without configuration -RUN mkdir -p /var/lib/wkhtml - -WORKDIR /var/lib/wkhtml -RUN wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.3/wkhtmltox-0.12.3_linux-generic-amd64.tar.xz && \ - tar -xvf wkhtmltox-0.12.3_linux-generic-amd64.tar.xz && \ - rm wkhtmltox-0.12.3_linux-generic-amd64.tar.xz && \ - ln -sf /var/lib/wkhtml/wkhtmltox/bin/wkhtmltopdf /usr/bin/wkhtmltopdf - -RUN bundle config --global frozen 1 + rm -rf /var/lib/apt/lists/* RUN mkdir -p /usr/src/app WORKDIR /usr/src/app COPY Gemfile /usr/src/app/ -COPY Gemfile.lock /usr/src/app/ - -#Ruby knows best how to install this particular version of PAC -#This means that this dockerfile can build any version of PAC. -RUN bundle install --without=test_gems COPY . /usr/src/app -RUN ln -s /usr/src/app/pac.rb /usr/bin/pac +#Ruby knows best how to install this particular version of PAC CLI +RUN rake install VOLUME ["/data"] WORKDIR /data -COPY entrypoint.sh /usr/local/bin/entrypoint.sh - -ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] - CMD ["pac"] diff --git a/Gemfile b/Gemfile index 58b9a36..d65e2a6 100644 --- a/Gemfile +++ b/Gemfile @@ -1,18 +1,3 @@ -source "https://rubygems.org" -#pdfkit and kramdown reqires sudo apt-get install wkhtmltopdf on the machines -gem 'mercurial-ruby', :require => false -gem 'pdfkit' -gem 'rake' -gem 'rugged', '~> 0.24.0' -gem 'trac4r', :require => false -gem 'docopt' -gem 'ruby-fogbugz', :require => false -gem 'flexmock' -gem 'zip' -gem 'liquid' -gem 'xml-simple', '~> 1.1', '>= 1.1.5' -gem 'simplecov' -gem 'simplecov-rcov' -gem 'ci_reporter_test_unit' -gem 'rspec' -gem 'xmlrpc' +source 'http://rubygems.org' + +gemspec diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index 1433c98..0000000 --- a/Gemfile.lock +++ /dev/null @@ -1,142 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - addressable (2.4.0) - builder (3.2.3) - ci_reporter (2.0.0) - builder (>= 2.1.2) - ci_reporter_test_unit (1.0.1) - ci_reporter (~> 2.0) - test-unit (>= 2.5.5, < 4.0) - crack (0.4.3) - safe_yaml (~> 1.0.0) - descendants_tracker (0.0.4) - thread_safe (~> 0.3, >= 0.3.1) - diff-lcs (1.3) - docile (1.3.1) - docopt (0.6.1) - faraday (0.9.2) - multipart-post (>= 1.2, < 3) - flexmock (2.3.6) - gash (0.1.4) - open4 (>= 0.9.6) - git (1.4.0) - github_api (0.16.0) - addressable (~> 2.4.0) - descendants_tracker (~> 0.0.4) - faraday (~> 0.8, < 0.10) - hashie (>= 3.4) - mime-types (>= 1.16, < 3.0) - oauth2 (~> 1.0) - gli (2.17.1) - grancher (0.1.5) - gash - hashie (3.5.7) - highline (2.0.0) - jeweler (2.3.9) - builder - bundler - git (>= 1.2.5) - github_api (~> 0.16.0) - highline (>= 1.6.15) - nokogiri (>= 1.5.10) - psych - rake - rdoc - semver2 - json (2.1.0) - jwt (1.5.6) - liquid (4.0.0) - mercurial-ruby (0.7.12) - open4 (~> 1.3.0) - mime-types (2.99.3) - mini_portile2 (2.3.0) - multi_json (1.13.1) - multi_xml (0.6.0) - multipart-post (2.0.0) - nokogiri (1.8.3) - mini_portile2 (~> 2.3.0) - nokogiri (1.8.3-x64-mingw32) - mini_portile2 (~> 2.3.0) - oauth2 (1.4.0) - faraday (>= 0.8, < 0.13) - jwt (~> 1.0) - multi_json (~> 1.3) - multi_xml (~> 0.5) - rack (>= 1.2, < 3) - open4 (1.3.4) - pdfkit (0.8.2) - power_assert (1.1.3) - psych (3.0.2) - psych (3.0.2-x64-mingw32) - rack (2.0.5) - rainbow (3.0.0) - rake (12.3.1) - rdoc (6.0.4) - rspec (3.7.0) - rspec-core (~> 3.7.0) - rspec-expectations (~> 3.7.0) - rspec-mocks (~> 3.7.0) - rspec-core (3.7.1) - rspec-support (~> 3.7.0) - rspec-expectations (3.7.0) - diff-lcs (>= 1.2.0, < 2.0) - rspec-support (~> 3.7.0) - rspec-mocks (3.7.0) - diff-lcs (>= 1.2.0, < 2.0) - rspec-support (~> 3.7.0) - rspec-support (3.7.1) - ruby-fogbugz (0.3.0) - crack (~> 0.4) - multipart-post (~> 2.0) - rugged (0.24.6.1) - safe_yaml (1.0.4) - sdoc (1.0.0) - rdoc (>= 5.0) - semver2 (3.4.2) - simplecov (0.16.1) - docile (~> 1.1) - json (>= 1.8, < 3) - simplecov-html (~> 0.10.0) - simplecov-html (0.10.2) - simplecov-rcov (0.2.3) - simplecov (>= 0.4.1) - test-unit (3.2.8) - power_assert - thread_safe (0.3.6) - trac4r (1.2.4) - gli - gli (>= 1.1.0) - grancher - jeweler - rainbow - rainbow (>= 1.0.4) - sdoc - xml-simple (1.1.5) - xmlrpc (0.2.1) - zip (2.0.2) - -PLATFORMS - ruby - x64-mingw32 - -DEPENDENCIES - ci_reporter_test_unit - docopt - flexmock - liquid - mercurial-ruby - pdfkit - rake - rspec - ruby-fogbugz - rugged (~> 0.24.0) - simplecov - simplecov-rcov - trac4r - xml-simple (~> 1.1, >= 1.1.5) - xmlrpc - zip - -BUNDLED WITH - 1.14.6 diff --git a/README.md b/README.md index 98ca236..5095df3 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,6 @@ maintainer: JKrag --- -Issue tracking: -[![Groomed](https://badge.waffle.io/Praqma/Praqmatic-Automated-Changelog.png?label=Status%20-%20workable&title=Groomed)](https://waffle.io/Praqma/Praqmatic-Automated-Changelog) -[![Up Next](https://badge.waffle.io/Praqma/Praqmatic-Automated-Changelog.png?label=Status%20-%20up%20Next&title=UpNext)](https://waffle.io/Praqma/Praqmatic-Automated-Changelog) -[![Work In Progress](https://badge.waffle.io/Praqma/Praqmatic-Automated-Changelog.png?label=Status%20-%20in%20progress&title=InProgress)](https://waffle.io/Praqma/Praqmatic-Automated-Changelog) -[![Issues](https://img.shields.io/github/issues/Praqma/Praqmatic-Automated-Changelog.svg)](https://github.com/Praqma/Praqmatic-Automated-Changelog/issues) - - # Praqmatic Automated Changelog (PAC) Tool for creating automated, but pragmatic, changelogs. @@ -16,15 +9,13 @@ Tool for creating automated, but pragmatic, changelogs. PAC collects task references from SCM commit messages and creates changelog reports with additional information extracted from other systems, like your task management system. Compared to other changelog solutions, PAC is very flexible and customizable. The design allows you to solve the problems of having an unchangeable SCM commit history with incorrect task references. -![The workflow behind PAC for creating changelogs](/docs/process.png) - ## Features * Customizable change reports based on **Liquid templates** -* Collects task references in SCM commits from **Git** or **Mercurial (hg)** -* Extracts data from tasks systems like **Trac** and **JIRA** for the collected tasks +* Collects task references in SCM commits from Git +* Extracts data from tasks systems that has an open rest interface that returns `Json` (Basic authenticaton supported) * For task systems returning json data, all data can be used in the templates -* Supports **MarkDown**, **HTML** and **PDF** as report formats +* Supports any textual output format. I.e you can write a template to produce css, markdown, html etc.. * Supports extracting data from multiple referenced tasks systems at once * Supports creating changelog without data from external systems, basing it only on SCM commits * Easily create reports for several different audiences using data from several sources @@ -32,29 +23,13 @@ Compared to other changelog solutions, PAC is very flexible and customizable. Th PAC has a flexible internal design, making it easy to extend with support for additional report formats, task management systems and so on. -See our [roadmap](/roadmap.md) for future plans. - ## Demo -Take PAC for a quick spin with our demo scripts (requires Linux Bash, zip and docker). - -**Generate changelogs using only SCM commits** - - ./demo_setup_docker.sh - -This demo generates some reports based only on SCM commits of a small test repository. -After running the demo, look for the reports in `demorepo/idReportTestRepository/default.[pdf|html|md|` and `demorepo/idReportTestRepository/ids.md` +**Generates changelogs using data from GitHub** -**Generates changelogs using data from JIRA** + ./github_example.sh - ./demo_setup_docker_jira.sh - -This demo generates some reports through a custom template which uses data from SCM commits of a small test repository and a spun-up JIRA instance. - -**Try a manual demo using the pac-manuscript repository** - -The [pac-manuscript](https://github.com/praqma-test/pac-manuscript) repository is a short demonstration of how PAC works with Jira, where each step of gradually introduces more of the PAC configuration and features. -The readme in the repository explain how to use it, but the pac-maunscript repository is a imaginary example on a source code repository matching some Jira issues where the series of commits are introducing new PAC features. +This demo, using docker, generates some reports through a custom template which uses data from PAC's own repository where we mount the current directory and run PAC against it. If succesful, you should see a file in `reports/github-report.html`. ## Getting started @@ -73,6 +48,8 @@ This is an example of a simple configuration file. It collects task references f This simple example do not extract data from task systems. :general: + :strict: false + :ssl_verify: true :templates: - { location: templates/default_id_report.md, output: ids.md } @@ -84,11 +61,8 @@ This simple example do not extract data from task systems. - { pattern: '/PAC\-(\d+)', label: none } :vcs: - :type: git :repo_location: '.' -More about configuration in [Configuration](docs/configuration.md). - Help writing regexp using Ruby IRB see this litle howto: [Howto write regexp using IRB](docs/howto_write_regexp_using_irb.md) ### Simple template @@ -100,32 +74,29 @@ This example template simply lists the discovered issues as headers in a Markdow ## {{task.task_id}} {% endfor %} -More about templates in [Templates](docs/templates.md). - - ## Usage Basic usage examples for the PAC Ruby script: Show help - ./pac.rb -h + pac -h Get commits using tags from "Release-1.0" tag to "HEAD": - ./pac.rb from Release-1.0 --settings=./default_settings.yml + pac from Release-1.0 --settings=./default_settings.yml - ./pac.rb from-latest-tag "Release-1.0" --settings=./default_settings.yml + pac from-latest-tag "Release-1.0" --settings=./default_settings.yml Get commits using tags from "Release-1.0" to "Release-2.0" - ./pac.rb from Release-1.0 --to Release-2.0 --settings=./default_settings.yml + pac from Release-1.0 --to Release-2.0 --settings=./default_settings.yml - ./pac.rb from-latest-tag Release-1.0 --to Release-2.0 --settings=./default_settings.yml + pac from-latest-tag Release-1.0 --to Release-2.0 --settings=./default_settings.yml Get commits using latest tag of any name: - ./pac.rb from-latest-tag "*" --settings=./default_settings.yml + pac from-latest-tag "*" --settings=./default_settings.yml The above getting started is only a simple example, so to utilize all the features in PAC you can dive into the following sections. @@ -141,54 +112,57 @@ All available configurations option for PAC is described in the [Configuration]( Information on how to write templates for the changelog and use the extracted data can be found in the [Templates](docs/templates.md) section. -### Take PAC for a spin - -You can try PAC using our PAC Docker container and a zipped github repository we use for testing. See [Try PAC with a test repo and PAC docker image](docs/try_pac_with_test_repo_and_docker.md) - -### Running PAC +### Running PAC on Linux We recommend to use our supplied [`praqma/pac`](https://hub.docker.com/r/praqma/pac/) Docker image so you avoid configuring a Ruby environmnet yourself. -* See [Using the PAC docker image](docs/using_the_pac_docker_image.md). - -If you like to configure your own Ruby environment and run PAC as simple Ruby script (`pac.rb`) follow instruction below for Linux (Ubuntu) or Windows. - -* PAC requires Ruby version 2 or later. Currently tested with version 2.3.0 of Ruby. - - -### Run PAC on Linux (Ubuntu) - -Configure your Linux Ruby environment to run PAC and get PAC from sources: - -Prerequisites: - - * Ruby version 2 (you can see specific version in the [PAC docker image file](Dockerfile)) - * The `bundler` Ruby Gem - * Native libraries - for Ubuntu they are: `sudo apt-get install cmake libxslt-dev libxml2-dev wkhtmltopdf` - -Then get and use PAC: - -1. Clone the pac repository to your local machine: `git clone https://github.com/Praqma/Praqmatic-Automated-Changelog.git pac` -2. Optionally check-out the `latest` tag or a specific release tag if you don't want bleeding edge. -3. Change directory to `pac` (the git clone) and run the command `bundle install` to install all the used Ruby Gems. -4. Optionally add a symlink to `pac.rb` in your path, for example: `ln -s [your install directory]/pac.rb /usr/bin/pac` - -That's it. Test your installation by executing pac: `pac`. If you get a help screen the installation was successful. - ### Run PAC on Windows -Detailed instructions can be found in [Installing PAC on Windows](docs/windows_instructions.md). - +Detailed instructions can be found in [Running PAC on Windows](docs/windows_instructions.md). ## Support and maintenance -* PAC is maintained in the scope of [JOSRA](http://www.josra.org/). * Issue and work tracking is done using [Github issues](https://github.com/Praqma/Praqmatic-Automated-Changelog/issues) * Support requests and questions can be created as Github issue or send us an mail on support@praqma.net -* Our roadmap is availbe in [roadmap](/roadmap.md) ## Changelog +### 4.x.x + +**Incompatible with versions 3.x.x and below** + +Refocus effort on optimitzing the docker image, removing dependencies and focusing on pure rest/json based tasks systems. + +* The `jira` task system has been renamed `json` +* Additional ssl options added. `--ssl-verify` and `--ssl-no-verify` options. Defaults to `true` to turn on ssl verification +* New authorization section. Supports token auth with GitHub token authentication and Basic Authentication for other systems +* Also able to read .netrc files and using this information in Basic Authentication +* The configuration file is now interpreted using ERB. This means that you can use ERB code blocks like `<%= ...expression %>` in the configuration file. Useful if you want to have certain things happinging in a test environment and other things going on in a production envrionment. **WARNING** This can be a potential security issue + +``` + +:task_systems: + - + :name: json + :regex: + - { pattern: '/#(\d+)/', label: github } + :query_string: "https://api.github.com/repos/Praqma/Praqmatic-Automated-Changelog/issues/#{task_id}" + # Option 0: No auth. Just remove the :auth: section + # Option 1: GitHub token authentication (Store in Environment variable) + :auth: + :github: + :token: <%= ENV['GITHUB_API_TOKEN'] %> # + # Option 2: Use basic authentication with values from somewhere + :auth: + :basic: + :username: <%= ENV['BASIC_USR'] %> + :password: <%= ENV['BASIC_PW'] %> + # Option 3: Use .netrc file. Remember to mount the files to default location or known location when using docker. + :auth: + :basic: + :netrc: /data/.netrc +``` + ### 3.x versions **Incompatible with versions 2.x and earlier - see the [migration guide](docs/Migrating_2.X.X_to_3.X.X.md) for more information** @@ -221,12 +195,9 @@ For details on design and development info see [Developer information](docs/deve See also [contributing file](/CONTRIBUTING.md). -## CodeScene analysis -[![](https://codescene.io/projects/1494/status.svg) Get more details at **codescene.io**.](https://codescene.io/projects/1494/jobs/latest-successful/results) - -### Contributors +### Maintainers * Mads Nielsen (man@praqma.net) -* Bue Petersen (bue@praqma.net) -* Andrius Ordojan (and@praqma.net) * Thierry Lacour (thi@praqma.net) +* Jan Krag (jak@praqma.net) +* Claus Schneider (cls@praqma.net) diff --git a/Rakefile b/Rakefile index e1bb7da..1752e1a 100644 --- a/Rakefile +++ b/Rakefile @@ -1,4 +1,4 @@ -task :default => [:test] +task :default => [:test, :rspec] task :test do Dir.glob('test/unit/*.rb').each do |testfile| @@ -6,39 +6,14 @@ task :test do end end -task :functional_test do - Dir.glob('test/functional/*.rb').each do |testfile| - ruby "#{testfile} --verbose=verbose" - end -end - -task :functional_trac do - Dir.glob('test/functional/*trac*.rb').each do |testfile| - ruby "#{testfile} --verbose=verbose" - end -end - -task :functional_jira do - Dir.glob('test/functional/*jira*.rb').each do |testfile| - ruby "#{testfile} --verbose=verbose" - end -end - -task :functional_vcs do - Dir.glob('test/functional/*vcs*.rb').each do |testfile| - puts testfile - ruby "#{testfile} --verbose=verbose" - end +task :install do + require_relative 'lib/version.rb' + `gem build pac.gemspec` + `gem install pac-#{PAC::VERSION}.gem` end #Example task :rspec do - `rspec --format='html' --out='results.html'` + `rspec --format='html' --out='results.html'` end -task :coverage do - ENV['COVERAGE'] = 'on' - Rake::Task['test'].execute -end - - diff --git a/pac.rb b/bin/pac similarity index 75% rename from pac.rb rename to bin/pac index 4f3f01f..b6736fb 100755 --- a/pac.rb +++ b/bin/pac @@ -2,27 +2,14 @@ #encoding: utf-8 require 'docopt' require 'liquid' -require_relative 'lib/core' -require_relative 'lib/report' +require_relative '../lib/core' +require_relative '../lib/version' +require_relative '../lib/report' doc = Core.cli_text(__FILE__) begin require "pp" - - #Versioning strategy see the file docs/versioning.md - #We need to read where the symlink points to because the docker container links pac to /usr/bin - def version - path = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__ - dir = File.dirname(path) - if File.exist?(dir+'/version.stamp') - version = File.read(dir+'/version.stamp') - else - version = "Version "+File.read(dir+'/version.properties').split("=")[1] - end - version - end - input = Docopt::docopt(doc) #This should print out any and all errors related to creating settings for PAC. This captures @@ -63,18 +50,23 @@ def version #Takes the list of discovered tasks, and only needs the template settings generator = Report::Generator.new(tasks, commit_map) generator.generate(Core.settings) - unless everything_ok + if !everything_ok if Core.settings[:general][:strict] + Logging.verboseprint(0, '[PAC] Error: Errors encountered while fetching data') exit 15 else - Logging.verboseprint(1, '[PAC] Ignoring encountered errors. Strict mode is disabled.') + Logging.verboseprint(0, '[PAC] Error: Ignoring encountered errors. Strict mode is disabled.') exit 0 end + else + if Core.settings[:general][:strict] then Logging.verboseprint(0, '[PAC] Strict mode is enabled!') end + Logging.verboseprint(0, '[PAC] Success!') + exit 0 end rescue Docopt::Exit => e puts "Praqmatic Automated Changelog (PAC)" - puts "#{version}\n" + puts "#{PAC::VERSION}\n" puts e.message puts end diff --git a/default.yml b/default.yml new file mode 100644 index 0000000..172c092 --- /dev/null +++ b/default.yml @@ -0,0 +1,17 @@ +:general: + :strict: false + :ssl_verify: false + +:templates: + - { location: templates/examples/github.html, output: 'github-report.html'} + +:task_systems: + - + :name: json + :regex: + - { pattern: '/#(\d+)/', label: none } + :query_string: "https://api.github.com/repos/Praqma/Praqmatic-Automated-Changelog/issues/#{task_id}" + +:vcs: + :type: git + :repo_location: '.' diff --git a/demo_setup_docker.sh b/demo_setup_docker.sh deleted file mode 100755 index f9266d0..0000000 --- a/demo_setup_docker.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/bin/bash -rm -rf demorepo/ -mkdir demorepo -unzip test/resources/idReportTestRepository.zip -d demorepo/ -cat << EOF > demorepo/idReportTestRepository/default_settings.yml -:general: - :strict: true - -:templates: - - { location: /usr/src/app/templates/default_id_report.md, output: ids.md } - - { location: /usr/src/app/templates/default.md, output: default.md } - - { location: /usr/src/app/templates/default_html.html, pdf: true, output: default.html } - -:task_systems: - - - :name: none - :regex: - - { pattern: '/.*Issue:\s*(?[\d+|[,|\s]]+).*?\n/im', label: none } - - { pattern: '/.*Issue:\s*?(none).*?\n/im', label: none} - :delimiter: '/,|\s/' - -:vcs: - :type: git - :usr: - :pwd: - :repo_location: '.' - :release_regex: 'tags' -EOF -docker build -t praqma/pac:snapshot . -docker run --rm -v $(pwd)/demorepo/idReportTestRepository:/data praqma/pac:snapshot from f9a66ca6d2e6 diff --git a/demo_setup_docker_jira.sh b/demo_setup_docker_jira.sh deleted file mode 100755 index 4e436ee..0000000 --- a/demo_setup_docker_jira.sh +++ /dev/null @@ -1,88 +0,0 @@ -#!/bin/bash -#Very simple demonstration script that starts off -rm -rf demorepo/ -mkdir demorepo -unzip test/resources/idReportTestRepository.zip -d demorepo/ - -#Write a series of commits that we can match. We want to show that data ends up in the -cd demorepo/idReportTestRepository -echo "FAS-1" > fas1.txt -git add fas1.txt -git commit -m"Fixed FAS-1 Added fas1" - -echo "FAS-2" > fas2.txt -git add fas2.txt -git commit -m"Fixed FAS-2 Added fas2" - -echo "FAS-3" > fas3.txt -git add fas3.txt -git commit -m"Fixed FAS-3 Added fas3" - -cd .. -cd .. - -#Now we have this repository: - -#* f818a48 Fixed FAS-3 Added fas3 -#* 287be34 Fixed FAS-2 Added fas2 -#* 690a6aa Fixed FAS-1 Added fas1 -#* fb49307 Test for multiple -#* 55857d4 Test for empty -#* a789b47 Test for none reference -#* cd32697 Updated readme file again - third commit -#* a7b63f1 Revert "Updated readme file" -#* 881b321 Updated readme file -#* f9a66ca Initial commit - added README - - -cat << EOF > demorepo/idReportTestRepository/default_settings.yml -:general: - :strict: true - -:templates: - - { location: /data/jira_template.md, output: jira.md } - -:task_systems: - - - :name: jira - :debug: true - :regex: - - { pattern: '/(FAS-\d+)/', label: jra } - :query_string: "http://localhost:28080/rest/api/latest/issue/#{task_id}" - :usr: 'admin' - :pw: 'admin' - -:vcs: - :type: git - :repo_location: '.' -EOF - -#We write a very simple jira template inside the repository we're mounting and adding to our container. -cat << EOF > demorepo/idReportTestRepository/jira_template.md -# {{title}} -{% for task in tasks.jra %} -## {{task.task_id}} - -### Summary - -{{task.attributes.data.fields.summary}} - -### Description - -{{task.attributes.data.fields.description}} - -### Associated commits -{% for commit in task.commits %} -- {{commit.shortsha}}: {{commit.header}} -{% endfor %}{% endfor %} -EOF - -#Start an instance of jira. We need this to get data from Jira. For now we just use the container we built for test -#This can be adapted or removed if you already have a running instance of Jira configured. -./test/resources/start_task_system.sh "jira" - -#Run PAC. We do it by mounting our repository inside the container. -docker build -t praqma/pac:snapshot . -docker run --rm --net=host -v $(pwd)/demorepo/idReportTestRepository:/data praqma/pac:snapshot from f9a66ca6d2e6 -#Stop it again, if needed for this we just use the one that came with the test -./test/resources/stop_task_system-jira-0000.sh "jira" \ No newline at end of file diff --git a/docs/Migrating_1.X.X_to_2.X.X.md b/docs/Migrating_1.X.X_to_2.X.X.md deleted file mode 100644 index 3ea2dc5..0000000 --- a/docs/Migrating_1.X.X_to_2.X.X.md +++ /dev/null @@ -1,108 +0,0 @@ -# Migrating from 1.x to 2.x - -With the introduction of PAC 2.0, the settings file formatting has changed. -The change isn't backwards compatible, so you will need to edit your settings file when upgrading from 1.x. - -In the following example, we upgrade a simple 1.x settings file: - -## Old format - -```YAML -:general: - date_template: "%Y-%m-%d" - changelog_name: "changelog" - changelog_formats: - - "html" - - "pdf" - changelog_css: - verbose: false - -:none: - regex: - - '/(JENKINS-[0-9]+)/i' - -:vcs: - type: git - usr: - pwd: - repo_location: "." -``` - -## New format - -```YAML -:general: - date_template: '%Y-%m-%d' - :strict: false - -:templates: - - { location: templates/default.md, output: changelog.md } - - { location: templates/default_html.html, pdf: true, output: changelog.html } - -:task_systems: - - - :name: none - :regex: - - { pattern: '/(JENKINS-[0-9]+)', label: none } - -:vcs: - :type: git - :repo_location: '.' -``` - -## Migration steps - -The changed needed to are explained in details below. - -### :general: - - 1. Remove `changelog_name` and `changelog_formats`. These setting are now part of the `:templates:` section. - 2. Remove `changelog_css:` and `verbose:` as they have been deprecated. - -### :templates: - -Previous attributes `changelog_name`, `changelog_css` and `changelog_formats` are all deprecated and replaced with templates. -You need to have at least one template specified to produce an output. - -To generate three output files in 1.x (`changelog.md`, `changelog.html` and `changelog.pdf`), you would have specified the following options in your settings file: - -```YAML -:general: - changelog_name: "Changelog" - changelog_formats: - - "html" - - "pdf" -``` - -To produce the same output files in the new format, replace the old configuration with templates. Add the following as your `:templates:` section - -```YAML -:templates: - - { location: templates/default.md, output: Changelog.md } - - { location: templates/default_html.html, pdf: true, output: Changelog.html } -``` - -Don't forget to create the Liquid templates defined in the `location:` attribute on the template items. For examples of Liquid templates, take a look at the examples included in the `templates` folder of this project. More information regarding templates can also be found in the project's `README` file. - -### :task_systems: - -If you used the task systems `none` or `trac`, move them under the `:task_system:` section using the list notation demonstrated below: - -```YAML -:task_systems: - - - :name: '[trac/none]' -``` - -Next, add a `:regex:` section under your task system. Move your regex into the new section as a `pattern` and asssign a grouping `label` to it. - -```YAML - :regex: - - { pattern: '/[your pattern]', label: [matching_issues] } -``` - -_Note:_ Previously a capture group named `` was required in your regex. This is no longer the case. Now the first capture group is used and one regex can have multiple matches on the same commit. - -### :vcs: - -Both `usr` and `pw` have been removed. diff --git a/docs/Migrating_2.X.X_to_3.X.X.md b/docs/Migrating_2.X.X_to_3.X.X.md deleted file mode 100644 index 2f17672..0000000 --- a/docs/Migrating_2.X.X_to_3.X.X.md +++ /dev/null @@ -1,36 +0,0 @@ -# Migrating from 2.x to 3.x - -With the introduction of PAC 3.0, a couple of things have changed: - -1. The previously deprecated `--sha` parameter has been completely removed, as `from` provides the exact same functionality. -2. All `date`-related functionality has been removed, as it was imprecise and difficult to use. - -This means that the only remaining ways of querying is `from` and `--to` as well as `from-latest-tag`, greatly simplifying use of pac. -With the removal of `date`, there is no longer any reason to have `date_template` defined in settings files. When upgrading to 3.0, it is recommended to remove this parameter from settings files, or at least make sure not to add it to any new files. It is not a breaking change, as the parameter is just unused in the future. - -## Old format - -```YAML -:general: - date_template: "%Y-%m-%d" - changelog_name: "changelog" - changelog_formats: - - "html" - - "pdf" - changelog_css: - verbose: false -[...] -``` - -## New format (date_template removed) - -```YAML -:general: - changelog_name: "changelog" - changelog_formats: - - "html" - - "pdf" - changelog_css: - verbose: false -[...] -``` \ No newline at end of file diff --git a/docs/SoW/svn-support.md b/docs/SoW/svn-support.md deleted file mode 100644 index 6c7fb34..0000000 --- a/docs/SoW/svn-support.md +++ /dev/null @@ -1,21 +0,0 @@ -# SVN support for PAC - statement of work - -## Problem - -Currently PAC only supports Git as a version control. We want to enable users of SVN to also automatically generate a changelog based on the same principle as in the Git implementation. - -## Solution - -We'll integrate the new features in the existing application, all changes will be fully backwards compatible. - -## Implementation - -The solution will be implemented using the Subversion command line tool. We'll make use of the tool's ability to output changes in an XML format for easier parsing. There are several similar tools out there which can be used as inspiration in the implementation. - -## Deliveries - -We'll distribute the source code as-is on GitHub, and also build and publish a working docker image with the new svn features. - -## Work load - -Estimated workload is about 37 hours, including test, release and publication. \ No newline at end of file diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index 3bea514..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,120 +0,0 @@ -# Configuration - -Below is an example of a full PAC configuration file which uses all features from PAC. -Each configuration part is explained below so you can pick and choose for your own project. - -Configuration file is YAML, so the : (colons), - (dash) and indentation matters. - - :general: - :strict: false - - :properties: - title: 'Changelog name' - product: 'Awesome product' - - :templates: - - { location: templates/default_id_report.md, output: ids.md } - - { location: templates/default.md, output: default.md } - - { location: templates/default_html.html, pdf: true, output: default.html } - - :task_systems: - - - :name: none - :regex: - - { pattern: '/Issue:\s*(\d+)/i', label: none } - - { pattern: '/Issue:\s*(none)/i', label: none } - - { pattern: '/(#\d+)/', label: none } - - { pattern: '/us:(\d+)/', label: none } - :delimiter: '/,|\s/' - - - :name: jira - :debug: false - :query_string: "http//your.server.hostname/jira/rest/api/latest/#{task_id}" - :usr: "user" - :pw: "password" - :regex: - - { pattern: '/PRJ-(\d+)/i', label: jira } - - - :name: trac - :trac_url: "https://my.trac.site" - :trac_usr: "user" - :trac_pwd: "pass" - :regex: - - { pattern: '/Ticket-(\d+)/i', label: trac } - - :vcs: - :type: git - :repo_location: '.' - -## General - -### strict - -**`strict`** If set to true PAC returns a non-zero exit code when a referenced task cannot be looked up your task system. - -_Defaults to `false`_. - -## Properties (_optional section_) - -This section specifies properties that you want to use in your template. You can specify any arbitrary number of properties in this section. In the example shown above, the following variables can be referenced in Liquid: - -- `{{properties.title}}` -- `{{properties.product}}` - -These values can be overridden at runtime by adding the `--properties` option when running PAC. Run PAC with the `-h` switch for an explanation on how to set a correct value for the `--properties` option. - -## Templates - -One or more [template configurations](templates.md). Each will result in a changelog report. -Put one template configuration pr. line - -**`- { location: , output: }`** - -Location and output values can be either relative (to PAC) or absolute. -Each item should point to a Liquid template crafted for your changelog report and the destination for output. - -You can specify a boolean **`pdf: true`** only together with HTML templates and HTML output. We require valid html in order to render pdf documents since we use a library called `pdfkit` to convert html files to pdf. As such there is no way for us to control the way the pdf is rendered, so if you do not like the way pdfkit renders your html you're free to use a different tool to create your pdf, an example could be the built in pdf printer in modern browsers. - -_`pdf` defaults to false._ - -## Task Systems - -One or more task system configurations. Note the - (dash) before each. - -A task system configuration must specify: - -* **`name`** (_required_) one of `trac`, `jira`, `none`. Selects task system to extract data for collected tasks in the SCM commits. The `none` is special as it do not extract data from any task system. You only have the collected task references from the SCM commit messages. -* **`regex`** (_section is required_) is a list of regular expressions used to find the tasks in the SCM commits. Each entry is in the form: `{ pattern: , label: