Development Guidelines

Welcome!

Awesome! You want to help with developing OpenConext-engineblock! On this page you will find all information required to get started with development.

Getting your hands on a development instance

As with deployments, the recommended way of getting an environment is using OpenConext-deploy. Please read the README.md and DEVELOPMENT.MD on how to get started with your development environment.

Note: at the moment of writing you are required to use the engineblock5-centos7 branch

Branching Model

OpenConext-engineblock has adopted the Github flow as the branching model. For a quick and easy introduction view this explanation.

Development guidelines

At the moment of writing EngineBlock is in the middle of a migration where the application is migrated to a Symfony based application as well as being streamlined so that it gains more focus on it's core capability: handling SAML Authentications. An effect of this is that there basically are two applications that cooperate:

• the original, Zend Framework and Corto based application, located in the library folder
• the "new", Symfony based application, located in the app and src folder.

As a rule of thumb, new functionality should be created in the Symfony based application. If unsure, please open an issue first asking for help.

Coding Style

With regards to coding style, the PSR-2 coding style has been adopted. All new code should adhere to the PSR-2 coding style, with one exception: code located in the library folder. This code predates the PSR-2 adoption and therefor should adhere to the Zend Framework 1 coding style.

Automatic Verfication

PHP_CodeSniffer is used to verify code style compliance. Furthermore, PHP Mess Detector (PHPMD) is used to enforce some code quality rules. In exceptional situations warnings generated by these rules can be suppressed, this should only be done if there is no good/better alternative. Lastly, php lint is used to ensure all code is syntactically correct. These tools are run as part of the code-quality checks,

Testing

Different Tests

• Unittests: for unittests PHPUnit is used. Unittests myst be created in the tests folder, mimicking the folder structure of the project itself. As a convention, tests should describe which behavior of the unit under test is being verified. Also each test should contain at least one, preferably two @group annotations. One should be the logical group the test belongs to (e.g. Doctrine, Logger), the other the high-level component the test belongs to (e.g. EngineBlock, EngineBlockBridge). More groups may be added if relevant.
• Integration Tests: for integration tests PHPUnit can be used as well. For integration tests the same structuring and grouping applies as for unittests.
• Acceptance Tests for automated acceptance testing Behat is used. For now all scaffolding, fixtures, mocks etc. used for the acceptance tests are placed in the EngineBlockFunctionalTestingBundle. The features and contexts should also be placed inside this bundle.

Using Tests During Development

During development features and scenario's can be placed in the WIP profile using the @WIP annotation. This ensures that those features and scenario's run in a build that is allowed to fail. This enables to specify the feature(s) and/or scenario(s) that verify the correctness of the functionality while still creating said functionality, thus creating acceptance tests.

In order to facilitate fast feedback loops, a git pre-commit and a git pre-push hook have been created. These can be installed using ant install-git-hooks. These run some tools before a commit and before a push so that you get faster feedback loops. You are encouraged to use them so that potential errors or design issues are caught as soon as possible.

Test Requirements

All new code should be covered by tests. For new or changed functionality, a feature or scenario must be created. The same goes for bugfixes. This allows for automated verification of the functionality/bugfix ensuring no regressions occur. All tests are run automatically for all Pull Requests against the master branch (see build tooling below). Besides the functional tests, as a general rule, unit- and integration tests should be created for all code.

Build Tooling

Continuous Integration

Travis-CI is used as Continuous Integration platform. For all pull requests against the master branch, a new build is started using the build matrix. There are two different builds for each supported PHP version, a functional tests build that runs the funtional tests and a code-quality-ci build that runs the code quality tools and the unit- and integrationtest suites. Furthermore there are "allowed failure" builds in the Matrix that run the @WIP functional tests and run the tests against PHP versions that will be supported in the future.

Task Runner

As a task runner, Apache Ant is used. There are several targets that can be used:

Target	Explanation
build	Target used by the CI, runs all tasks, assumes a Test environment
pre-commit	Target run by the pre-commit hook, runs all tests suites and code quality checks
pre-push	Target run by the pre-push hook, runs all tests suites, code quality checks and functional tests; requires a development environment
functional-tests	Target that executes the functional test regression suite in a non-development environment (used by the CI)
functional-tests-wip	Target that executes the functional test WIP suite in a non-development environment (used by the CI)
code-quality-ci	Target that runs the code quality tools and the test-suites.
code-quality	Target that runs the code quality tools (linter, PHPMD and PHP_CodeSniffer)
test-suites	Target that runs the unittest and integration test suites

There is also experimental Make integration, see PR #334.

Releasing

In order to build a new release, please use the bin/makeRelease.sh script. This will create a clean release, a tarball of that release, and a file containing the sha1 sum of the tarball in the ~/Releases directory. Do note that you are required to give a branch- or tagname of the release to be built. The tarball will be used for deployments, the sha1 sum for integrity verification of the tarball. If a new tag has been made, please upload the tarball and the sha1 sum to the tag using the github releases page. In case of an upgrade path or BC breaks, please document these in the UPGRADING.md file to help other adopt the new version.

Theme Development

The layout and styling of EngineBlock is taken care of in a so-called theme. This allows for having a default theme, but at the same time allows the development of multiple different themes. All themes are created in the theme folder, each in a separate folder.

For development of a theme the following tools are required:

• Node.JS
• Bower (requires Node.JS)
• Compass

After installing the above tools, the following commandline may give you all the needed dependencies and run grunt to update the installed files after changing a theme:

(cd theme && npm install && sudo npm install -g bower && bower install && grunt)

When applying a theme for the first time you can enter the theme directory and run npm install and bower install to load the required theme modules.

Themes can be deployed using a Grunt task, from the theme directory run grunt theme:mythemename, this will initiate the appropriate tasks for cleaning the previous theme and deploying the new theme on your installation.

Do note that in order to see changes made to a theme, you have to deploy the theme using the aforementioned grunt task. This ensures that the theme is available. when running in a non-development environment, you will also have to run composer prepare-env to ensure that the cached templates are updated with the latest changes.