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 composer validate, which will point out schema errors.
Configuration
edit- prepend-autoloader:
false
. 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 this for some more details. - optimize-autoloader:
true
. No reason not to optimize.
Good example: core MediaWiki
Dependencies
editDependencies should be pinned to a specific version number or sha1 commit if a tag isn't available.
Good example: core MediaWiki
Naming
editLibraries hosted in Gerrit or by the Wikimedia GitHub account should typically be published under the "wikimedia" namespace (e.g. "wikimedia/cdb", "wikimedia/simplei18n"). The use of the "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
editMajor authors to the project should be documented in the "authors" property. At least the name and email fields should be filled out.
Extensions and skins
editExtensions
editExtension 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 "^2|^1.0.1"
), and the type needs to be set to "mediawiki-extension".
Good example: Bootstrap extension
Skins
editMainly 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. mediawiki/vector-skin
), the extra.installer-name
property must be set to the uppercase name (e.g. Vector
) so it is cloned in the right directory.
Good example: Vector skin
Overlaps with extension.json and skin.json
editExtensions and skins register information about themselves using an extension.json
or skin.json
file.
Some metadata fields in these files overlap, including:
homepage
vs.url
license
vs.license-name
The redundancy of data between extension/skin.json and composer.json has been discussed (see task T89456), but current consensus is that it is unavoidable.