Continuous integration/Tutorials/Adding a MediaWiki extension

From MediaWiki.org
Jump to: navigation, search

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[edit]

  • 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 (php tests/phpunit/phpunit.php --testsuite extensions).

Editing Zuul configuration[edit]

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. That is all what is needed. You can then send it for review, your configuration will be automatically validated and diffed with the previous configuration.

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

Advanced[edit]

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.