Manuel:Bonnes pratiques pour composer.json
Lorsque vous créez un fichier composer.json pour votre extension/bibliothèque/etc qui sera utilisée dans MediaWiki, voici quelques bonnes pratiques à suivre. Vous devriez aussi lancer le validateur de Composer qui vous pointera les erreurs de schéma.
Configuration
- prepend-autoloader:
false
. L’auto-chargeur (autoloader) de Composer est plus lent que celui de MediaWiki et la plupart des classes chargées sont susceptibles d’être trouvées dans MediaWiki, donc ajoutez après, plutôt que avant l’auto-chargeur de Composer. Voyez ceci pour les détails supplémentaires. - optimize-autoloader:
true
. Il n’y a pas de raison de ne pas optimiser.
Bon exemple : mediawiki/core
Dépendances
- Les dépendances doivent être fixées à un numéro de version ou un commit sha1 spécifique si un label n’est pas disponible.
Bon exemple : mediawiki/core
Nommage
Les bibliothèques hébergées dans Gerrit dans par le compte GitHub Wikimedia devraient typiquement être publiées dans l’espace de noms « wikimedia » (par exemple « wikimedia/cdb » , « wikimedia/simplei18n »). L’utilisation de l’espace de noms « mediawiki » devrait être réservée aux extensions ou autres composants intrinsèquement liés à MediaWiki (les cadriciels de bots, etc.). Il est suggéré aux projets hébergés sur GitHub dans une organisation indépendante d’adopter une convention similaire pour qu'un espace de noms d’organisation soit utilisé de façon cohérente dans toutes les bibliothèques publiées par le groupe.
Auteurs
Les noms des auteurs principaux du projet doivent être documentés dans la propriété « auteurs ». Au minimum, les champs du nom et du courriel doivent être remplis.
Extensions et habillages
Extensions
Les noms des extensions doivent être en minuscules avec des tirets -
comme séparateurs de mots. Par exemple :
- Extension:WikiEditor → mediawiki/wiki-editor
- Extension:MassMessage → mediawiki/mass-message
Pour les rendre installables, une dépendance de "composer/installers" avec la version >= 1.0.1 est requise (une valeur raisonnable pour ce champ est "^2|^1.0.1"
), et le type doit être fixé à mediawiki-extension
.
Bon exemple : mediawiki/extensions/Bootstrap
Habillages
Principalement comme les extensions, à la différence que le type devrait être « mediawiki-skin ». Les noms devraient finir avec le suffixe « -skin ».
Parce que Composer utilise les noms en minuscules pour les paquets (par exemple mediawiki/vector-skin
), la propriété extra.installer-name
doit être le nom en majuscules (c'est à dire Vector
) afin qu'il soit copié dans le bon répertoire.
Bon exemple : mediawiki/skins/Vector
Recouvrements par extension.json et skin.json
Les extensions et les habillages enregistrent leurs propres informations en utilisant un fichier extension.json
ou skin.json
.
Certains champs de métadonnées de ces fichiers se recouvrent, y compris :
homepage
vs.url
license
vs.license-name
La redondance des données entre extension/skin.json et composer.json a été discutée (voir tâche T89456), et le consensus actuel est que cela est inévitable.