Skip to content
This repository
Browse code

Updated README (fixes #8)

  • Loading branch information...
commit 45b57c997735b6bfe7df2445a90b143b931beff4 1 parent 0ec09b2
James Harris jmalloc authored

Showing 1 changed file with 88 additions and 1 deletion. Show diff stats Hide diff stats

  1. +88 1 README.md
89 README.md
Source Rendered
@@ -3,12 +3,17 @@
3 3 [![Build Status](https://api.travis-ci.org/IcecaveStudios/woodhouse.png)](http://travis-ci.org/IcecaveStudios/woodhouse)
4 4 [![Test Coverage](http://icecave.com.au/woodhouse/coverage-report/coverage.png)](http://icecave.com.au/woodhouse/coverage-report/index.html)
5 5
6   -**Woodhouse** provides a simple way to publish your PHPUnit code coverage reports to GitHub pages. It was originally designed to run in a [Travis CI](http://travis-ci.org) build, but can be used in any environment.
  6 +**Woodhouse** is a command line utility (and PHP library) for publishing build artifacts such as test reports and code coverage metrics to a GitHub pages repository.
  7 +It was originally designed to run in a [Travis CI](http://travis-ci.org) build, but can be used in any environment.
7 8
8 9 ## Installation
9 10
10 11 **Woodhouse** requires PHP 5.3.3 or later.
11 12
  13 +### Download executable
  14 +
  15 +* Run `curl http://icecave.com.au/near/near > near` or [download now](http://icecave.com.au/near/near)
  16 +
12 17 ### With [Composer](http://getcomposer.org/)
13 18
14 19 * Add 'icecave/woodhouse' to the project's composer.json dependencies
@@ -19,3 +24,85 @@
19 24 * Clone from GitHub: `git clone git://github.com/IcecaveStudios/woodhouse.git`
20 25 * Use a [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md)
21 26 compatible autoloader (namespace 'Icecave\Woodhouse' in the 'lib' directory)
  27 +
  28 +## Features
  29 +
  30 +### Publishing artifacts
  31 +
  32 +The most basic feature of **Woodhouse** is publication of build artifacts. Artifacts are
  33 +specified as pairs of source and destination paths, separated by colons.
  34 +
  35 + $ woodhouse bob/widget report.html:artifacts/tests.html --auth-token 0bee...8a33
  36 +
  37 +The example above publishes a file called `report.html` in the current directory
  38 +to `artifacts/tests.html` in the `gh-pages` branch of the `bob/widget` GitHub repository.
  39 +
  40 +Many artifacts can be published in a single commit by specifying multiple source:destination pairs.
  41 +The source path may reference individual files or directories.
  42 +
  43 +### Build status badges
  44 +
  45 +**Woodhouse** is able to parse several common test report formats to deduce the result of a build
  46 +and publish an appropriate status image. This image can be used in your GitHub README file or on
  47 +a website to show the current status of the build. The images at the top of this document are
  48 +published in this way.
  49 +
  50 + $ woodhouse bob/widget --build-status-image img/status.png --build-status-junit junit.xml --auth-token 0bee...8a33
  51 +
  52 +This example parses `junit.xml` to determine the build status, and then publishes the appropropriate
  53 +status image to `img/status.png`.
  54 +
  55 +The supported test report formats are:
  56 + * JUnit XML
  57 + * TAP (Test Anything Protocol)
  58 + * PHPUnit JSON
  59 +
  60 +You can also specify the build status directly on the command line using the `--build-status-result` option.
  61 +
  62 +### Coverage badges
  63 +
  64 +Much like the build status images, **Woodhouse** can also publish images showing the percentage of the code based covered by tests.
  65 +
  66 + $ woodhouse bob/widget --coverage-image img/coverage.png --coverage-phpunit coverage.txt --auth-token 0bee...8a33
  67 +
  68 +This example parses `coverage.txt` (A file created using PHPUnit's `--coverage-text` option) to determine
  69 +the coverage percentage, and then publishes the appropropriate image to `img/coverage.png`.
  70 +
  71 +You can also specify the coverage percentage directly on the command line using the `--coverage-percentage` option.
  72 +More coverage formats will be supported in a future version.
  73 +
  74 +### Image themes
  75 +
  76 +**Woodhouse** uses [ezzatron/ci-status-images](https://github.com/ezzatron/ci-status-images) as a source for the build status and coverage images.
  77 +There are several themes and variants available. The desired theme(s) can be chosen with the `--image-theme` option.
  78 +
  79 +If no theme is specified [travis/variable-width](https://github.com/ezzatron/ci-status-images/tree/master/img/travis) is used.
  80 +
  81 +## Security
  82 +
  83 +**Woodhouse** requires a GitHub OAuth token with write access to publish content.
  84 +
  85 +**This token must be kept secure, anyone with access to this token can masquerade as you on GitHub.**
  86 +
  87 +If you are using [Travis CI](http://travis-ci.org) you can use
  88 +[encrypted environment variables](http://about.travis-ci.org/docs/user/build-configuration/#Secure-environment-variables) to
  89 +store your token such that it can only be decrypted by Travis. To complement this feature, **Woodhouse** provides the
  90 +`--auth-token-env` option to read your token from an environment variable, preventing it from being logged to the console.
  91 +
  92 +Please note that although it is tempting to create a separate GitHub account for publishing of artifacts, this is explicitly
  93 +prohibited by the [GitHub Terms of Service](https://help.github.com/articles/github-terms-of-service).
  94 +
  95 +### Creating a GitHub token
  96 +
  97 +To acquire a GitHub token you need to create an authorization using the
  98 +[GitHub API](http://developer.github.com/v3/oauth/#create-a-new-authorization). This only needs to be done once for your
  99 +GitHub account (not for each repository). The command below can be used to create such an authorization.
  100 +
  101 + $ curl -u <github-username> \
  102 + -d '{"scopes":["repo"],"note":"icecave/woodhouse"}' \
  103 + https://api.github.com/authorizations
  104 +
  105 +### Revoking a GitHub token
  106 +
  107 +If you suspect your token has been compromised, it can be revoked on the [application settings](https://github.com/settings/applications) page.
  108 +You will then need to create a new token as described above.

0 comments on commit 45b57c9

Please sign in to comment.
Something went wrong with that request. Please try again.