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.

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 its 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. Since EB 5.7, Zend Framework has been removed completely.
• 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 therefore 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 and automatically verified by the CI. You are encouraged to use the git hooks or build tools provided to run these tools yourself (see the section "Build Tooling" below)

Testing

Different Tests

• Unittests: for unittests PHPUnit is used. Unittests must 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 Acceptance 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. Once the functionality has been created and/or adapted so that the acceptance tests pass, the @WIP annotation can be removed. The acceptance tests are then ran as part of the regression test suite.

In order to run the acceptance tests, you can use the git hooks or the build tools provided, see the section "Build Tooling" below.

Test Requirements

All new code should be covered by tests. For new or changed functionality, an acceptance test (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 acceptance 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 accep[tance 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 acceptance tests, as well as buils that run all 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.

Git Hooks

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. For information about what each hook exactly runs, please refer to the ant targets above.

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 tag name 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.

Release notes

As of version 5.9 we'll start keeping the CHANGELOG.md in the repository. While working on a new release in master, please keep track of important changes in the changelog under a 'development' release. The changelog entries can go into detail about any and all changes that are introduced in that release. Where we will post a summary of these changes to the release notes in GitHub.

Theme Development

The layout and styling of EngineBlock are 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
• Compass

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

(cd theme && npm install && grunt)

When applying a theme for the first time you can enter the theme directory and run npm 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.

As of version 5.7, we use Twig templates instead of Zend_Layout (.phtml) templates. When implementing a custom theme please update your app/config/config.yml file. Updating the paths of the twig section, to use the correct theme.

For example change the default values:

twig:
    paths:
        "%kernel.root_dir%/../theme/material/templates/modules": theme
        "%kernel.root_dir%/../theme/material/templates/layouts": themeLayouts

To:

twig:
    paths:
        "%kernel.root_dir%/../theme/MyTheme/templates/modules": theme
        "%kernel.root_dir%/../theme/MyTheme/templates/layouts": themeLayouts