Guide for contributors

Required software

We use the following software for development:

• PHP 5.3: The library uses namespaces and anonymous functions!
• PHPUnit 4.0 as our testing framework. (Currently, the test framework should also work on PHPUnit 3.7, but we don't guarantee it.)
• phpDocumentor 2 to generate source code documentation.
• If you are using Windows, you'll need Windows PowerShell to run the build script.
• If you are using Sublime Text, the repository contains a project file with some useful settings and build systems.

Coding Conventions

We follow the Zend Framework's Coding Standards (ZF 2) with the following exceptions/additions:

• All files end with a new line character.
• Opening braces for control blocks are always placed on a new line. That means the only opening braces placed on the same line are those that open anonymous functions.
• Single-line control statements may omit braces IF the condition only consists of a single line, too.
• If the first of a two-letter acronym is capitalized in a name, so is the second (e.g. getID() but setUrl()).
• All but the simplest regular expressions have to be formatted in free-spacing mode and thoroughly commented.
• Do not use features from PHP 5.4 or newer! (including traits, short array syntax, function array dereferencing, $this in closures, generators, finally and others...)

If you want to contribute, please try to adhere to these conventions.

Using the repository

We roughly follow this branching model.

The stable branch is called master and only contains one (merge) commit for each release, which is also tagged with the release version.

We only use one release branch for all releases. This is where you make final tests of the release, potentially fix remaining bugs, write release notes and build the documentation. Once the release is finished it is merged into the master and the development branch. (Note: Don't do the merging for the actual release yourself - see further down for build scripts.)

The development branch is where the next version is being developed. You can create additional branches to work on individual features, but don't have to. Once all features for a new release are completed, merge development into release and wrap up the new version there.

Finally, there is a src-only branch which contains the contents of the master branch's src directory. You shouldn't touch this branch manually - it's kept up-to-date by the build script (see next section). Releases are tagged here as well. This branch can be used if you only need the library without its tests or documentation (for instance, we use this in the demo).

Building new versions

The largest part of wrapping up a release is taken care of by the build-release.ps1 (Windows, PowerShell) or build-release.sh (Unix) script.

When all features for the next release are finished, merge all feature branches into development and development into release. Test the features there and fix any bugs that occur. There is no need to build the documentation with PHPDoc.

Then add a new entry to CHANGELOG.txt. This is where you choose the new version number. Whatever version number you enter into the change log will be used by the build script. Make sure to commit the CHANGELOG.txt. Important: When choosing the new version, make sure it is compliant with Semantic Versioning

Now run the appropriate build script for your system. We recommend that you use git's credential cache or an SSH agent, otherwise you'll have to enter your GitHub credentials a few times during build process. The script will build the documentation, merge everything into master, create a new release tag and also keep the src-only branch up-to-date.

Note that the build script does not merge release back into development. If that is necessary (e.g. because you fixes bugs in release), you'll have to do it manually at the end.

Note: The build-script still needs to be ported to Unix. Currently, only the PowerShell script build-script.ps1 works. If you want to contribute to the library and are using a Unix system, please port the build script first or create an issue here on GitHub.