Configuration

sorah edited this page Sep 27, 2012 · 3 revisions

Configuration

(Still needs improvements.)

Try

Run pendaxes --init to generate .pendaxes.yml, then find pending in *_spec.rb in your repository, finally generates report to ./report.html.

To try this config file, just run pendaxes.

$ pendaxes
./.pendaxes.yml not found.
Usage: pendaxes [config file]
$ pendaxes --init
Just written default config file to "./.pendaxes.yml" !

In default configuration, this will do:

1. Detect pendings
2. Write report file to "./report.html"

For more about configuration, see https://github.com/cookpad/pendaxes/wiki/Configuration !

$ pendaxes
=> Using ./.pendaxes.yml
...
$ open report.html

Generate defaults

just run pendaxes in your repository to generate default configuration to .pendaxes.yml.

$ pendaxes --init
Just written default config file to "./.pendaxes.yml" !

In default configuration, this will do:

1. Detect pendings
2. Write report file to "./report.html"

For more about configuration, see https://github.com/cookpad/pendaxes/wiki/Configuration !

or, specify git remote url and path to use

             where to write  remote git url           where to clone
                  VVV               VVV                    VVV
$ pendaxes --init config.yml git@example.com:repo.git /tmp/pendaxes_repo
Wrote default config file to config.yml
with using git@example.com:repo.git (will be cloned to /tmp/pendaxes_repo)

If you want to customize, just edit config file! (default: .pendaxes.yml)

Details of config file is described below.

Detail of configuration

Default configuration without comments:

workspace:
#  path: /tmp/repository
#  repository: git@github.com:foo/bar.git

notifications:
  - use: file
    to: report.html
    reporter:
      use: haml

detector:
  use: rspec
  pattern:
  - '*_spec.rb'

Know the architecture

First, knowing the architecture will help you:

                                         +----------+
                                         | Reporter |
                                         +----------+
                                            ^   |
                                   Pendings |   | Report (text or html, ...)
                                            |   v
              +----------+  Pendings   +-------------+
*_spec.rb --> | Detector | ----------> | Notificator |
              +----------+             +-------------+
                                              |
                                              v
                                        mail, file, etc
  • Detector: Detects the pendings. Currently rspec is only available.
  • Reporter: generates a report. ("report" is formatted pendings into String. HTML or text)
  • Notificator: sends report as mail, write report into file, etc.

We can use 1 detector, and multiple notificators and 1 reporter for 1 notificator.

Workspace

workspace:
  path: /tmp/repository
  repository: git@github.com:foo/bar.git
  • if path set:

    • if path doesn't exist, repository (git remote url) will be cloned to path.

      • Will raise error if both repository and path are not set.
    • if path exists, pendaxes doesn't clone again.

    • pendaxes don't check path is valid git repository.

    • IMPORTANT: Pendaxes does git reset --hard in path, if path set.

  • if path not set:

    • Use same directory of config file will be used.
    • if path not set, pendaxes does not git reset --hard, but don't take care that working copy is clean.

Notifications

notifications:
  - use: file
    to: report.html
    reporter:
      use: haml

notifications is array of notification config.

(These settings are available at all notificators)

  • use: which notificator to use. (available notificators in default, described below)
  • reporter: configuration of reporter for this notification. described below.

Note: You can use same notificator & reporter multiple time.

Notificators

file, mail and terminal is available in default.

file
  - use: file
    to: report.html

Save report to file.

  • to: file path where you want to save report.
mail
  - use: mail
    reporter:
      use: haml

    from: no-reply@example.com

    delivery_method: sendmail
#   delivery_options:
#     :foo: bar

#   to: developers@example.com
#   whitelist:
#     - allowed@example.com
#     - /example\.com$/
#   blacklist:
#     - black@example.com
#     - /^black/
#   alias:
#     "foo@example.com": "bar@example.com"

mail sends mails to each committers about their left pendings.

  • from: used as From of sent mail.

  • delivery_method: choose delivery_method. we're using mikel/mail gem.

  • delivery_options (optional): options for delivery_method.

    • Note: YAML a: b become {'a' => 'b'} in Ruby, YAML :a: bbecome{:a => 'b'}` in Ruby.
    • Pendaxes doesn't make sure that keys in delivery_options are Symbols.
  • to (optional): if set, mail sends only 1 mail to this value including all pendings in a repository, instead sending mails to committers.

  • whitelist (optional): if set, mail won't be sent to addresses not match to any of this list.

    • if value of this surrounded by / (like /^.+$/), will be used as Regexp.
    • if not, will be used for exact match.
  • blacklist (optional): mail won't be sent to addresses that match to any of this list. blacklist is preferred than whitelist.

    • Regexps are accepted as same as whitelist.
  • alias (optional): replace committers' address.

Reporters

text and haml is available in default.

text
reporter:
  use: text

No configurations.

Example output:

* a_spec.rb:15 - pending 'because it fails.' (@ <sha1> 2012-09-27 10:47:25 +0900)
* a_spec.rb:10 - pending 'because it fails' (@ <sha1> 2012-09-27 11:40:15 +0900)
haml
reporter:
  use: haml
# commit_url: "https://github.com/user/repo/commit/%commit%"
# file_url: "https://github.com/user/repo/blob/HEAD/%file%#L%line%"
# message: "<p>Hey you should fix your left pendings.</p>`
  • commit_url (optional): if set, a text of commit hash becomes link to this value. %commit% will be replaced to commit hash.
  • file_url (optional): if set, a text of file path becomes link to this value. %file% will be replaced to file path, and %line% become line number.
  • message (optional): if set, value will be inserted right after of header. (HTML)

Example output:

sample notification using mail with haml

Detector

detection:
  use: rspec
# pattern:
#   - '*_spec.rb'

Currently rspec is only available.

rspec finds pending, xit, xexample, xspecify from files (matches to `pattern) in your repository.

  • use (optional, default: rspec): which detector to use. currently rspec only.
  • pattern (optional, default: ['*_spec.rb']): pattern for rspec file. this will be passed to git grep --.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.