User:Osnard/Composer best practice DRAFT

Developer resources

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

On packagist.org

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

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

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

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

Developers

Choose a maintenance model

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

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

"mediawiki"

Administrators

Use release branches

Most MediaWiki extension do not have semantic versioning. The WMF as well as some extension authors support certain release branches. Using a release branch as version constraint will therefore ensure compatibilty to your Mediawiki Core version.

Example:

{
    "require": {
        "mediawiki/visual-editor": "dev-REL1_35"
    }
}

Be aware that usually only the current LTS branch(es) as well as the branch of the latest release receive patches.

Use third-party package repositories

Not all MediaWiki extensions are listed on packagist.org. But you can add additional repositories to your composer.json

{
    "repositories": [{
        "type": "composer",
        "url": "https://packages.bluespice.com/"
    }]
}