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

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.

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

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.

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.

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)

• 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.

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.

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.

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.

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

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

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.

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.

In order to release a theme you could use EB_THEME=theme ./makeRelease.sh where EB_THEME is the theme name used.

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.

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.

Engineblock ships with a base theme which serves as the fallback theme for anything which is not overriden by the current theme. On the base theme currently two themes are built: skeune (default and included with built assets in the tarball) and material. It is possible to create your own theme based on the base theme.

Each custom theme will be fully self-contained and import the css/js it wants from the base theme. The base theme is set up so as to allow easy overwriting of variables (through the use of the !default option for sass). Only templates from the base theme which need to be overriden should be in here. Anything that can stay the same, simply stays the same. The way that works is decribed here.

You can set the desired theme name in parameters.yml: This will load the correct Twig templates as they are a part of the Symfony config.

parameters:
    # Other parameters have been left out for brevity
    theme.name: skeune

Next build the front-end assets for the selected theme.

(cd theme && npm ci && npm run build)

Finally, when not in an environment with the debug flag enabled, you need to clear the cache. This will ensure the translations and templates are swapped out for the ones found in the new theme.

$ php72 ./app/console cache:clear --env=prod

All tried and tested cache functions can be used in EngineBlock. The most common task is to clear/warmup the cache.

/opt/openconext/OpenConext-engineblock $ ./app/console cache:clear --env=dev

When running EngineBlock in development mode using the Vagrant setup we provide clearing and warming the cache can be very slow. The shared filesystem does not like to perform many IO tasks and will throttle disk performance.

That's why we chose to save the dev cache to the /tmp folder of the virtual machine. This increases cache performance significantly. The downside is that you can no longer access the cache files from outside your guest machine.