Continuous integration/Tutorials/Adding a MediaWiki extension

This tutorial is aimed at adding automatic tests for a new MediaWiki extension. You will learn how to verify the tests are going to work properly and how to edit the Wikimedia platform configuration to enable continuous testing.

We will base all our commands to adds jobs for the DonationInterface MediaWiki extension. That will include PHP and javascript linting, and running unit tests with a MediaWiki installation.

Prerequisites
You should have a working Jenkins job builder installation already. If not please follow the step by step guide to install Jenkins Job Builder.

A labs account to be able to submit your changes for review to Wikimedia Gerrit install.

Your extension does install using a SQLite backend.

Make sure all PHP files are valid:

find. -name '*.php'|xargs -n1 php -l

As well has Javascript ones:

jshint.

And of course the unit tests should pass.

Editing Jenkins configuration
Since you have installed Jenkins Job Builder, aim at the configuration directory fetched under config. Extensions are defined in mediawiki-extensions.yaml.

The YAML file is pretty easy to edit, the first definitions you encounter are job templates which have a name and several placeholders, you can think about them as function parameters:

The template is part of a job-group, which is a nice way to call several job templates in just one call. The mwext-check-jobs group below would generate four jobs:

The job group itself is called from a project:

When encountering a project, Jenkins job builder will invokes the four templates defined in mwext-check-jobs and pass them the project parameters. Hence it will call '{name}-{ext-name}-lint' with the parameters name = mwext, ext-name = AbuseFilter and mwbranch = master.

To generate jobs for the DonationInterface, we simply have to add an entry under ext-name</tt> and Jenkins jobs builder will call all the job-group templates with ext-name = DonationInterface</tt>

Save the file, you have completed the configuration.

Now run Jenkins jobs builder in testing mode to verify its properly creating the new jobs:

$ mkdir output $ jenkins-jobs test -o output ./config $ ls -1 output/*DonationInterface* output/mwext-DonationInterface-jslint output/mwext-DonationInterface-lint output/mwext-DonationInterface-testextensions-master $

They are written using the XML format Jenkins use to describe jobs.

You can then git add the modified YAML file and submit it for review and later deployment.

See CI/JJB to deploy the change in Jenkins. Which is, once JJB is properly setup, all about doing:

jenkins-jobs --conf etc/jenkins_jobs.ini update config/ job1 job2 job3...

You will then need to change Zuul configuration to have it trigger the jobs.

Editing Zuul configuration
Once your jobs have been deployed in Jenkins, they need to be run whenever an action is made in Gerrit, such as a new patchset being submitted or a change being merged. That is the role of Zuul which is listen for Gerrit events and has a specification to trigger certain jobs on certain events.

The configuration is held in integration/zuul-config.git</tt> repository which has a single file: layout.yaml.

The file is made of four sections:

- pipelines : define event filtering and result handling behavior - jobs: finely adjust the behavior on a per job basis - project-templates : define common jobs triggering - projects: define, for a Gerrit repository, the pipelines to uses and the hierarchy of jobs being triggered.

We provide a template for MediaWiki extensions that will trigger unit tests:

As you can see, that is pretty similar to Jenkins Job Builder syntax.

To add the triggers for the DonationInterface extension, we should add a new entry in the project</tt> section and invoke the template:

Save the file. That is all what is needed. You can then send it for review, a Jenkins job will validate your configuration and another job does a diff with the previous configuration.

To have it deployed, see the Zuul page, that requires shell access on the server running it.

For your own extension
The extension must be hosted on Wikimedia git infrastructure under the mediawiki/extensions/</tt> git hierarchy. We do not support running tests hosted on foreign git repositories.

Your extension PHP entry point MUST be named the same as the extension, that is how Jenkins will load it up in the installed MediaWiki. For DonationInterface we had DonationInterface/DonationInterface.php</tt>.