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, as well as running unit tests with a MediaWiki installation.

Prerequisites

• A Wikimedia Gerrit account to be able to submit changes for review
• A MediaWiki extension hosted in Wikimedia Gerrit in a repository named mediawiki/extensions/ExtensionName
• The extension must install properly using a MySQL database backend
• Your extension must be using extension.json, or if using the legacy PHP entry point, that file must be named the same as the extension, e.g. ExtensionName/ExtensionName.php

• The composer/npm entry points should be set up, if not check the BoilerPlate extension for predefined ones.
• Verify that the unit tests pass (composer phpunit:entrypoint -- --testsuite extensions).

Editing Zuul configuration

Terminology note: Zuul is the system that schedules jobs to be run after a patch is uploaded or approved in Gerrit. Jenkins is the job runner, that communicates with Zuul.

The configuration is held in integration/config repository, in the file zuul/layout.yaml.

The file is made of four sections:

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

To add the triggers for the DonationInterface extension, we should add a new entry in the project section and invoke extension-unittests-generic template:

project:
  - name: mediawiki/extensions/DonationInterface  # Gerrit project name
    template:
      - name: extension-unittests-composer  # invoke the template above for unit tests and linting through composer
      - name: mwgate-npm # run npm test too

Save the file and send it for review. Your changes will be diffed with the previous configuration, and if you are listed in the CI Whitelist, your configuration will be automatically validated.

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

CI allow list

If your checks do not run after your configuration has been merged, check to see whether you are listed in the CI allow list. Only those on the list can trigger jobs.

Advanced

The Jenkins job injects specific configuration at the end of MediaWiki LocalSettings.php. You can find them under integration/jenkins.git repository in directory /mediawiki/conf.d/. It sets for example the global $wgWikimediaJenkinsCI which let you finely tweak your extension setting when running tests, for example to enable a feature which you want disabled by default but for which you have tests.

If your extension has dependencies on other extensions, they can be added to the mapping in zuul/parameter_functions.py.