2016 Ibuildings Development Practices

Ibuildings Development Quality Assurance - Process and Tools

Ibuildings

Ibuildings April 2016

Postbus 1525 3500 BM Utrecht T +31 (0)88 00 24 000 www.ibuildings.nl KvK 22046933

Contents 1. Introduction .................................................................................................. 3 2. The Ibuildings Coding Standards ................................................................... 4 2.1.

2.2.

2.3.

2.4.

2.5.

2.6.

PHP Code Style ..................................................................................................... 4 PHP Mess Detection ............................................................................................. 5 PHP Copy/Paste Detection .................................................................................... 5 JavaScript Code Style ............................................................................................ 6 Code Documentation ........................................................................................... 6 Security................................................................................................................ 8

3. The Ibuildings Development Environment ...................................................... 9 3.1. Automated Provisioning ....................................................................................... 9 3.2. Automated Deployment ....................................................................................... 9 3.3. The Ibuildings QA-Tools ....................................................................................... 9 3.3.1. Static code analysis ........................................................................................ 9 3.3.2. Automated tests ............................................................................................ 9 3.3.3. Security ......................................................................................................... 9 3.3.4. Version control integration ............................................................................ 9 3.4. PHPUnit.............................................................................................................. 10 3.5. Behat, automated functional tests ...................................................................... 11 3.6. BrowserStack, manual functional tests ............................................................... 12 3.7. Github, Pull Requests and Code Reviews ............................................................ 12 3.8. Continuous Integration Server ............................................................................ 13

4. The Ibuildings Development Process: A Day in The Life of a Feature ............ 15 4.1. Continuous Deployment..................................................................................... 16 4.2. Code Reviews ..................................................................................................... 17 4.3. Best Practices ..................................................................................................... 17

2 / 17

1. Introduction To guarantee the great quality of our deliverables, we use the same development process and tools for all development projects. This ranges from tools that enforce our coding standards through static code analysis to parts of the process that make sure that all code is always seen by more than one pair of eyes.

An important factor in making sure quality is high and consistent, is automating repetitive tasks as much as possible, thereby reducing the chance of errors. Ibuildings applies this principle as much as possible in its development process. We will describe how repetitive tasks in Quality Assurance are automated using which tools. This is part of the Ibuildings Development Environment.

Once we are familiar with the environment all development takes place in, we can zoom in on the development process. The best way to describe all elements of our process is by following the lifecycle of a feature as it is being developed. We will see it going through the Ibuildings Development Process, touching all tools involved.

The context of both the Ibuildings Development Environment and the Ibuildings Development Process are the Ibuildings Coding Standards. These standards describe what we want our deliverables to look like. As long as this is applied consistently in all projects, quality will be assured.

3 / 17

2. The Ibuildings Coding Standards The Ibuildings Coding Standards apply in several different areas: the code formatting, the code architecture, documentation and security. In this paragraph we describe the standards we use in each area. Where applicable, this is split per programming language.

2.1. PHP Code Style In general we use the PSR set of coding standards as described by the PHP Framework Interop Group, specifically PSR-1, PSR-2, PSR-3 and PSR-4. Where necessary we amend this standard with framework-specific standards. Since the Drupal coding standard differ from PSR we comply to the Drupal coding standard when using the Drupal framework.  PSR-1: http://www.php-fig.org/psr/psr-1/  PSR-2: http://www.php-fig.org/psr/psr-2/  PSR-3: http://www.php-fig.org/psr/psr-3/  PSR-4: http://www.php-fig.org/psr/psr-4/  Drupal Coding Standard: https://drupal.org/coding-standards Example output from the PHP Code Sniffer:

The PHP Code Sniffer is part of the Ibuildings QA-Tools. See the paragraph ‘The Ibuildings Development Environment’ for a description.

4 / 17

2.2. PHP Mess Detection Apart from these standards for code formatting we have rules for certain characteristics of code. In developer lingo, these are called ‘code smells’. We use the rules as defined here: http://phpmd.org/rules/index.html, with a few exceptions to reduce false positives.

An overview:  All Unused Code rules, except:  UnusedFormalParameter  All Code Size rules  All Controversial rules  All Design rules  All Naming rules, except:  ShortVariable  LongVariable  All Clean Code rules, except:  BooleanArgumentFlag  ElseExpression  StaticAccess Example output from PHP Mess Detector:

The PHP Mess Detector is part of the Ibuildings QA-Tools. See the paragraph ‘The Ibuildings Development Environment’ for a description.

2.3. PHP Copy/Paste Detection As a general rule, it is considered a bad practice to copy/paste code. Repeated code of more than 5 identical lines or 70 identical characters is considered copy/pasted.

Example output from PHP Copy/Paste Detector:

5 / 17

The PHP Copy/Paste Detector is part of the Ibuildings QA-Tools. See the paragraph ‘The Ibuildings Development Environment’ for a description.

2.4. JavaScript Code Style In general we use the Airbnb coding style. See https://github.com/airbnb/javascript When using Drupal we use the Drupal JS coding standard. The Drupal JS coding standard is described at https://www.drupal.org/node/172169 Example output from JSHint:

JSHint is part of the Ibuildings QA-Tools. See the paragraph ‘The Ibuildings Development Environment’ for a description.

2.5. Code Documentation In addition to the above code style rules, we enforce for all programming languages that enough in-code documentation is written. The rules are simple: ● every function should have a docblock comment that accurately reflects the function signature and return value. ● ambiguous code must be documented inline with a comment explaining the rationale behind the code. ● TODO and FIXME comments must not be committed but an issue should be created in the issue tracker instead.

Example of both function docblock and an inline comment explaining ambiguous code:

6 / 17

7 / 17

2.6. Security All custom code that we write is checked to make sure that it does not introduce a security vulnerability from the OWASP Top Ten. If applicable, we decide together with the client if and what level of the OWASP Application Security Verification Standard (ASVS) the project will support. This is verified by doing an ASVS audit during the project.

3rd party code used in our projects is not audited unless as part of the selected ASVS level. Using the Sensiolabs Security Checker we do a limited check for known security issues in one of the projects 3rd party PHP dependencies.

For Drupal we keep track of the security announcements at https://www.drupal.org/security and keep the 3rd party code current.

8 / 17

The Open Web Application Security Project (OWASP) is a worldwide not-for-profit charitable organization focused on improving the security of software. Our mission is to make software security visible, so that individuals and organizations worldwide can make informed decisions about true software security risks.

3. The Ibuildings Development Environment 3.1. Automated Provisioning To reduce unexpected bugs during deployment, all development within Ibuildings takes place on Virtual Machines (VMs) that mirror the production environment down to the operating system. These VMs are automatically provisioned with Ansible.

3.2. Automated Deployment To reduce unexpected bugs during deployment as much as possible, all deployments within Ibuildings are automated as much as possible. For automated deployment we use the tools Capifony (Symfony), Drush (Drupal) and Ansible.

3.3. The Ibuildings QA-Tools The Ibuildings QA-Tools are a set of automated code inspection and test tools that are run at different stages of the development process. The QA-Tools enforce the Ibuildings Coding Standards and throw errors when the inspected code does not adhere to the standard.

To make sure that the Ibuildings QA-Tools are used by all developers in all projects the tools are installed on all development VMs during project setup. This is not optional.

The following tools are part of the QA-Tools:

3.3.1. Static code analysis    

JSHint (jshint.com) PHP Mess Detector (phpmd.org) PHP Code Sniffer (https://github.com/squizlabs/PHP_CodeSniffer) PHP Copy Paste Detector (https://github.com/sebastianbergmann/phpcpd)

3.3.2. Automated tests  

PHPUnit (http://phpunit.de/) Behat (http://behat.org/)

3.3.3. Security 

Sensiolabs Security Checker (https://security.sensiolabs.org/)

3.3.4. Version control integration 

9 / 17

A custom Git commit hook that executes the QA-Tools on every commit. This way, if an error is detected during code analysis or test runs, the commit is rejected and never makes it into the shared code base.

3.4. PHPUnit The de-facto standard for writing Unit Tests in PHP is PHPunit (http://phpunit.de/).

It is used by all major PHP frameworks. We write unit tests for all separately testable units of code, where relevant. In our opinion it is useless to blindly aim for 100% code coverage. That is why we determine what parts of the code need to be covered by unit tests per individual project.

Unit tests do not test functionality, but code logic. A good example of pieces of code that need to be unit tested is a component that represents an amount of money and supports certain operations on that amount.

Example code: <?php class Money { private $amount; public function __construct($amount) { $this->amount = $amount; } public function getAmount() { return $this->amount; } public function negate() { return new Money(-1 * $this->amount); } // ... }

Example Unit test: <?php class MoneyTest extends PHPUnit_Framework_TestCase { // ... public function testCanBeNegated() { // Arrange $a = new Money(1); // Act $b = $a->negate();

10 / 17

// Assert $this->assertEquals(-1, $b->getAmount()); } // ... }

Example output from PHPUnit:

On that note: Drupal 7 uses SimpleTest. Wherever we write custom Drupal code that is not tied directly to the Drupal framework, we will still use PHPUnit. For all other parts of Drupal applications we use automated functional testing. This suits the nature of Drupal applications much better than unit tests.

3.5. Behat, automated functional tests Behat is a tool that makes behavior driven development (BDD) possible. With BDD, you write human-readable stories that describe the behavior of your application. These stories can then be auto-tested against your application.

This has several advantages:  end users can understand and discuss the tests  this kind of tests are very suitable for running integration tests  this kind of test is very suitable for testing User Interfaces Example Behat story:

11 / 17

Example Behat output:

If, and how much Behat tests will be written depends on the kind of project. The more User Interface there is to test, the more Behat tests there will be compared to Unit tests.

3.6. BrowserStack, manual functional tests To test websites and applications in multiple browsers on multiple platforms, we use BrowserStack. This is where manual testing takes place.

See http://www.browserstack.com/

3.7. Github, Pull Requests and Code Reviews We use Github as our hosted distributed version control server mainly for this reason: GitHub supports Pull Requests (PR). Pull Requests are central to the Ibuildings Development Process.

12 / 17

A Pull Request is what triggers a code review by one of the developers peers in the project. Without PRs, it would be much, much harder to ensure code reviews are actually done. Using PRs, this is automatic.

To be able to explain what a Pull Request is, we first need the context of the branching model and the entire Ibuildings Development process. PRs will be explained in that paragraph in more detail. Finally, a Code Review can be described in the context of PRs. See https://github.com/ and https://help.github.com/articles/using-pull-requests

3.8. Continuous Integration Server We use TravisCI (http://travis-ci.org) as our Continuous Integration (CI) server. The CI server runs the QA-Tools and all tests on every commit to the master (production) branch on GitHub and for every Pull Request that request the code merged to the master branch.

The result of the master build is projected on the wall board (a TV showing the wall board is featured prominently in all Ibuildings offices). The master branch may never be broken.

If it is, that is a reason for someone to approach the development team. A broken build on the master branch can compromise the security, quality and proper operation of the software and therefore should not be happing at all times.

Example fictional wall board:

13 / 17

The CI servers most important role is as a notification and early warning system. It makes it almost impossible to deploy broken code: that would mean ignoring build errors on both Pull Requests and on the master branch after merging a PR. Another very useful function of the CI server is keeping a history of builds. This makes it possible to get an idea of project quality fluctuations over time.

14 / 17

4. The Ibuildings Development Process: A Day in The Life of a Feature In this paragraph we will follow a feature as it is being developed. We will see how it travels through the Ibuildings Development Environment and how the Ibuildings Coding Standards are applied to it.

1. The developer is assigned a User Story or development task. a. Tools: we use Atlassian JIRA for task management.

2. The developer starts work on the feature. He does this by creating a feature branch. a. We use GitHub as our version control system. b. We use Git-Flow as our branching model: http://nvie.com/posts/asuccessful-git-branching-model/ 3. The developer changes writes some code.

4. The developer makes a commit to his feature branch.

5. The Git pre-commit hook automatically runs the QA-Tools on the commited changeset. This build is run locally on the developers Virtual Machine. a. If the build fails, the commit is rejected and the developer has to start again at 3. The commit never left the developers workstation. b. If the build succeeds, the commit is accepted. Nothing is pushed to Github.

6. The developer adds some more code by iterating 3-5.

7. The feature is ready. The developer pushes the feature branch to Github.

8. The developer creates a Pull Request on Github for the feature branch a. Github notifies our Travis CI server to build the Pull Request branch b. Github notifies all project members that there is a new PR 9. Travis posts the build result back to Github. Github shows this status in the Pull Request screen.

10. A team member opens the Pull Request to start a Code Review a. The team member can add comments to the commited code, the developer can react to these comments. This way a PR is a repository of information and discussion about a feature b. The team member can see the Travis build status for this PR. If it has status failed, no Code Review needs to be done: the PR can be rejected. c. The team member can request some changes and an update of the PR. 11. If a Pull Request is rejected, and the team member asks the developer makes some changes, the developer goes back to 3. and iterates 3-10 until the PR is accepted.

12. If the Pull Request is accepted, the feature branch is merged into the master/develop branch by the team member and the PR is closed.

13. Github notifies Travis that the master branch has been updated and needs to be built.

14. Travis shows the build results on the wall board. And optionally sends e-mail about a failed to team members.

15. Done. Start next feature.

15 / 17

Example Pull Request with comments on GitHub:

Example Travis build status in a Github PR:

4.1. Continuous Deployment Optionally, the final step of the iterative Ibuildings Development Process could be this: 16. Travis builds a release version of the current master branch and deploys this to the production environment automatically.

That is called continuous deployment. Whether this is desirable, depends on the type of project and on the investment in the quality of the automated tests. If you are unsure that there will be no errors, even though all tests pass, would you update production without

16 / 17

anyone monitoring everything? Continuous Deployment sets extra demands for test quality but saves enormous amounts of time in the long run.

As mentioned above, Ibuildings does not blindly go for 100% code coverage. We write relevant tests that actually tell you something about the quality of the code. This is a requirement for Continuous Deployment.

4.2. Code Reviews As can be seen above, the manual code review in a Pull Request is now limited to things that automated tools can’t determine. Menial and black-and-white things don’t need to be done by humans anymore. This saves an enormous amount of time when aiming for good quality deliverables.

Code Reviews can now focus on things that require knowledge of context and human intelligence:  the business domain  software architecture

4.3. Best Practices A best practice is a method or technique that has consistently shown results superior to those achieved with other means, and that is used as a benchmark. In addition, a "best" practice can evolve to become better as improvements are discovered.

- Wikipedia This is where the built-in feedback loop of the Ibuildings Development Process comes in.

Many times, code reviews lead to new insights. This can be about a specific tool or framework, or about more generally applicable design principles. Whenever this is the case, the following is done:  If relevant to the project, the project Wiki is updated  the knowledge base about the subject on our internal Wiki is updated (Confluence)  if applicable to one of the Code Standards, the QA-Tools are updated  these updates are shared among all developers in the internal developer chat  if important enough, the insights are discussed in the bi-weekly Senior Developer meeting. This can lead to new company-wide policy

17 / 17