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 core MediaWiki]

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

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

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.

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 (a reasonable value for this field is ), and the type needs to be set to "mediawiki-extension".

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

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.

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

Overlaps with extension.json and skin.json
Extensions and skins register information about themselves using an <tvar|extension> </> or <tvar|skin> </> file. Some metadata fields in these files overlap, including:
 * <tvar|homepage> </> vs. <tvar|url> </>
 * <tvar|license> </> vs. <tvar|licensename> </>

The redundancy of data between extension/skin.json and composer.json has been discussed (see <tvar|phab></>), but current consensus is that it is unavoidable.