Manual:Composer.json best practices

When creating a composer.json file for your extension/library/etc that will be used inside MediaWiki, here are a few best practices to follow.

You should also run [https://getcomposer.org/doc/03-cli.md#validate composer validate], which will point out schema errors.

Configuration

 * prepend-autoloader: . Composer's autoloader is slower than MediaWiki's, and most of the classes being loaded are likely to be found inside MediaWiki, so append the composer autoloader instead of prepending it.  See [https://github.com/wmde/WikidataBuilder/pull/32 this] for some more details.
 * optimize-autoloader:.

No reason not to optimize.

Good example: [https://github.com/wikimedia/mediawiki/blob/master/composer.json mediawiki/core]

Dependencies

 * Dependencies should be pinned to a specific version number or sha1 commit if a tag isn't available.


 * For development tools like phpunit or phpcs, "dev-master" or "*" is acceptable.

Good example: [https://github.com/wikimedia/mediawiki/blob/master/composer.json mediawiki/core]

Naming
Libraries hosted in Gerrit or by the Wikimedia GitHub account should typically be published under the [https://packagist.org/packages/wikimedia/ "wikimedia" namespace] (e.g. "wikimedia/cdb", "wikimedia/simplei18n").

The use of the [https://packagist.org/packages/mediawiki/ "mediawiki" namespace] should be reserved for extensions and other intrinsically MediaWiki related components (bot frameworks, etc).

Projects hosted at GitHub under an independent organization are encouraged to adopt a similar convention of an organization namespace to be applied consistently across the libraries published by the group.

Authors
Major authors to the project should be documented in the [https://getcomposer.org/doc/04-schema.md#authors "authors"] property.

At least the name and email fields should be filled out.

For libraries, this will be displayed on Special:Version in the "Installed libraries" section.

Extensions
Extension names should be all lowercase with hyphens as word separators. For example:


 * Extension:WikiEditor → mediawiki/wiki-editor


 * Extension:MassMessage → mediawiki/mass-message

To make themselves installable, a dependency upon "composer/installers" with version >= 1.0.1 is required, and the type needs to be set to "mediawiki-extension".

Good example: [https://github.com/cmln/mw-bootstrap/blob/master/composer.json mediawiki/extensions/Bootstrap]

Skins
Mainly the same as extensions, except the type should be "mediawiki-skin".

The names should end with a suffix of "-skin".

Because composer uses lowercase names for packages (e.g. <tvar|vector> </>), the <tvar|name> </> property must be set to the uppercase name (e.g. <tvar|Vector> </>) so it is cloned in the right directory.

To make themselves installable, a dependency upon "composer/installers" with version >= 1.0.13 is required, and the type needs to be set to "mediawiki-skin".

Good example: [<tvar|url>https://github.com/wikimedia/mediawiki-skins-Vector/blob/master/composer.json</> mediawiki/skins/Vector]

Also extension.json
Extensions and skins register information about themselves using an <tvar|extension> </> or <tvar|skin> </> file. Some metadata fields in these files overlap (discussed in <tvar|phab></>), including
 * <tvar|homepage> </> and <tvar|url> </>
 * <tvar|license> </> and <tvar|licensename> </>