drupalci.md

Your DrupalCI Build

A guide for drupal.org project maintainers.

Note: Put this in a handbook page when it's been RTBCd.

What Is DrupalCI?

DrupalCI is a system that checks out the quality of projects hosted on drupal.org. We sometimes call it the 'testbot.'

What Is A Build Definition?

The DrupalCI testbot uses a YAML-formatted file to specify a 'build.' The build is all the things that happen when the testbot evaluates your patch.

The build definition file tells the testbot how to retrieve the codebase it's supposed to test, how to apply patches, how to run Composer, and so forth.

How Is The Build Definition Organized?

If you look at the default definition file, you'll see that it has a top-level key of build.

Under the build level we have what are called stages. These include codebase, environment, and assessment.

Within these stages are 'phases,' such as validate_codebase and testing. The generic term for any item in the build definition is a 'task.'

How Do I Override Default Behavior?

If you want your testbot builds to do something other than the default build, you should put it into a drupalci.yml file in the root of your project.

It should look like this:

build:
  assessment:
    # Your assessment stage stuff here.

Remember we said there are 'stages?' Well, your drupalci.yml file will replace the assessment stage. If you have a codebase or environment stage in your file, they will be ignored. That's so the testbot doesn't lose its mind.

You can use the tasks you see in the default file. They are not as greatly documented as they should be, but that will change.

You can also issue commands to the host environment and the containerized environment, like this:

    host_command:
      - test -f vendor/composer/installed.json
      - another command/here
    container_command:
      - composer update phpunit/phpunit --with-dependencies

You can also specify whether these tasks will halt the build or not. die-on-nonzero refers to the result code of the command you executed:

    container_command:
      die-on-nonzero: TRUE
      - composer update phpunit/phpunit --with-dependencies

And, finally, you can have more than one of these, if you give it a name by adding .name to the end of the task:

    container_command.setup:
      die-on-nonzero: FALSE
      - setup your/thing
      - setup other/thing
    container_command.showstopper:
      die-on-nonzero: TRUE
      - showstopper -v

Wait, Containerized Environment?

Currently, the testbot uses Docker to provide the PHP environment. If you want to run a PHP command in the PHP version you specified on D.O, you should run it under container_command.

Otherwise, host_command has a PHP version of 7.2, and might not in the future.

What Tasks Are Available To Me?

In addition to host_command and container_command, we have these ones, which you have to put inside their validate_codebase and testing keys:

    validate_codebase:
      phplint:
      container_composer:
      csslint:
      eslint:
      phpcs:
    testing:
      simpletest.standard:
        types: 'Simpletest,PHPUnit-Unit,PHPUnit-Kernel,PHPUnit-Functional'
      simpletest.js:
        concurrency: 1
        types: 'PHPUnit-FunctionalJavascript'
      nightwatchjs:

They all have configurations which you can learn about by examining the result builds of previous testbot runs, or by looking at them in code.

MORE DOCS PLEEZE.