Contributing to Imbo

Imbo is an open source project licensed with the MIT license. All contributions should ideally be sent in form of a pull request on GitHub. Please use features branches with descriptive names, and remember to send the pull request against the develop branch.

If you have found a bug in Imbo, please leave an issue in the issue tracker.

Build script

Imbo uses Rake for building, and if you have Rake installed you can simply run the rake command after cloning Imbo to run the complete build. You might need to install some additional tools for the whole build to complete successfully. If you need help getting the build script to work with no errors drop by the #imbo channel on IRC (Freenode) or simply add an issue in the issue tracker on GitHub.

Running the complete suite is not necessary for all contributions. If you skip the build script and simply want to get Imbo up and running for contributing you can run the following commands in the directory where you cloned Imbo:

curl -s https://getcomposer.org/installer | php
php composer.phar install

Remember to not include the --no-dev argument to composer. If you include that argument the development requirements will not be installed.

Requirements

When contributing to Imbo (or any of the other related packages) there are some guidelines you should follow.

Coding standard

Imbo has a coding standard that is partially defined as a PHP Code Sniffer standard. The standard is available on GitHub and is installable via PEAR. There are some details that might not be covered by the standard, so if you send a PR you might notice some nitpicking from my part regarding stuff not covered by the standard. Browse existing code to understand the general look and feel.

Tests

When introducing new features you are required to add tests. Unit/integration tests (PHPUnit) and/or Behat scenarios is sufficient. To run the PHPUnit test suite you can execute the following command in the project root directory after installing Imbo:

./vendor/bin/phpunit -c tests/phpunit

If you want to generate code coverage as well you can run the test suite by using a Rake task:

rake phpunit

For the Behat test suite you can run similar commands:

./vendor/bin/behat --strict --profile no-cc --config tests/behat/behat.yml

to skip code coverage, or

rake behat

for code coverage of the Behat tests. If you want to run both suites and collect code coverage you can execute:

rake test

Code coverage is located in build/coverage and build/behat-coverage respectively.

If you find a bug that you want to fix please add a test first that confirms the bug, and then fix the bug, making the newly added test pass.

Documentation

API documentation is written using phpDocumentor, and can be generated via a Rake task:

rake apidocs

End user documentation (the ones you are reading now) is written using Sphinx and is located in the docs/ directory in the project root. To generate the HTML version of the docs you can execute the following command:

rake readthedocs

This task also includes a spell checking stage.

Pull requests on GitHub

If you want to send a pull request, please do so from a publicly available fork of Imbo, using a feature branch with a self descriptive name. The pull request should be sent to the develop branch. If your pull request is fixing an open issue from the issue tracker your branch can be named after the issue number, for instance issue-312.