Composer/For extension developers

From mediawiki.org
Jump to navigation Jump to search

Developer resources[edit]

A more up to date list of instructions can be found in Introduction to Composer for MediaWiki developers.

On packagist.org[edit]

Packagist.org is the central composer package repository.

A "mediawiki" user exists on Packagist to have GitHub notify packagist whenever a new commit land in the repository. The credentials for the mediawiki user are only accessible to Wikimedia Foundation Operations team (they used to be on fenari:/home/wikipedia/doc/packagist.org but got moved RT #6665). Legoktm has access to the account, so poke him if you want a package added.

composer.json[edit]

You want to add a composer.json file in your extension. Here is an example from Translate:

{
	"name": "mediawiki/translate",
	"type": "mediawiki-extension",   
	"description": "Let your user translate any kind of text",
	"homepage": "https://www.mediawiki.org/wiki/Extension:Translate",
	"license" : "GPL-2.0+",

	"require": {
		"composer/installers": ">=1.0.1",
	},
	"suggest": {
		"mediawiki/translation-notifications": "Manage communication with translators"
	}
}

More examples can be found at Manual:composer.json best practices.

Then we check the syntax to avoid mistakes:

$ composer validate
./composer.json is valid

Test composer.json[edit]

Before you commit your composer.json, you should test it. There is a chicken-and-egg problem here. You must commit your extension's composer.json before you publish the extension in packagist. To solve this problem, you can use your local repository instead of packagist.

Add or edit the composer.local.json file in your main MediaWiki directory (your test environment) to add your local repository to composers list of repositories to look for packages.

The following example assumes you are using Git as your VCS. Because composers repository type vcs works with bare git repositories only (and not working trees) you must let the url-attribute point directly to your $GIT_DIR instead of your working tree (this is the .git-subdirectory inside your repository in most cases). Now add the following lines to the composer.local.json file:

...
    "repositories": [
        {
            "type": "vcs",
            "url": "ABSOLUTE_OR_RELATIVE_PATH_TO_YOUR_GIT_REPOSITORY/.git"
        }
    ],
...

Now you can test your extension's installation by specifying an according require-attribute inside your composer.local.json file. Composer will match an according tag or branch name from your local repository then.

Publish extension in packagist[edit]

See Manual:Developing libraries#Packagist guidelines for information on how to add your extension to packagist.org.

Developers[edit]

Choose a maintenance model[edit]

Release branch
You should provide patches to certain release branches (e.g. LTS and last stable) and make sure the extension works properly with the corresponding version of MediaWiki Core
Semantic versioning
Add tags according to SemVer. Make sure that compatibility to MediaWiki Core is only changed in major releases

Be packagist.org compatible[edit]

In your composer.json make sure you feature all fields that are required by a package repository like packagist.org.

Example:

{
    "name": "mediawiki/mycoolextension",
    "type": "mediawiki-extension",
    "extra": {
        "installer-name": "MyCoolExtension"
    },
    "require": {
        "composer/installers": "~1.0"
    }
}


Set proper keywords[edit]

  • "mediawiki"