Ecrire une extension pour le déploiement

Cette page documente les étapes nécessaires à un mainteneur ou un responsable de code d'une extension MediaWiki pour inscrire celle-ci dans le processus de révision afin qu'elle soit éventuellement déployée sur les wikis Wikimedia. Tout ce qui est déployé sur les serveurs Wikimedia doit être examiné pour des problèmes de sécurité et d'évolutivité. Là où l'expression « extension » apparaît ci-dessous, les mots « habillage » ou « code » sont synonymes.

L'écriture d'une extension en vue de son déploiement peut être un projet qui nécessite du temps ; toute personne intéressée est encouragée à démarrer le processus bien avant l'échéance.

Vous pouvez voir la liste de toutes les extensions en attente de relecture.

Lorsque qu'une extension a été validée, son déploiement peut être planifié par le gestionnaire des versions de la Fondation Wikimedia.

Liste de contrôle/processus

Prérequis généraux et attentes

Suivez les instructions générales et les recommandations sur l'écriture des extensions. Lisez les Conventions de codage, les Points de contrôle avant de valider, les Recommandations concernant les performances, ainsi que la Sécurité pour les développeurs et assurez-vous que votre code respecte ces recommandations.

• Documentation :
  • Créer une page Extension:My Extension dans l'espace de noms Extension : sur mediawiki.org pour informer les développeurs et les personnes qui installeront ou configureront l'extension. Utiliser Modèle:Extension pour cela. Vous pouvez utiliser le champ ci-dessous pour vous aider.
    
    
  • Créer une page Help:Extension:My Extension dans l'espace de noms Help:Extension: sur mediawiki.org pour la documentation de l'utilisateur final de votre extension. La relier à la page Extension:My Extension ci-dessus. Voir aussi la documentation du développement des extensions . Exemple : guide utilisateur de VisualEditor . Les captures d'écran peuvent aider à expliquer le fonctionnement. Vous pouvez utiliser le champ ci-dessous pour vous aider.
    
    
• hébergement du code - Demander un nouveau répertoire dans Git/Gerrit pour stocker le code source de votre extension. Gerrit est l'endroit où se fait toute la relecture du code.
• gestionnaire de problèmes - Demander un projet dans Phabricator pour suivre les bogues et les demandes de fonctionnalité pour votre extension. Recevez les notifications pour les nouvelles tâches attribuées à votre projet.
• assistance - Ajouter le projet sur la page Developers/Maintainers pour indiquer le responsable de sa gestion et de sa maintenance à long terme.
• traduction - Votre extension doit être traductible sur Translatewiki.net avant de pouvoir être déployée. Ce qui signifie que votre code doit avoir ses propres fichiers i18n, etc.
  • Une fois que l'extension est déployée sur un wiki de test Wikimedia, elle doit être ajoutée au groupe des nouvelles extensions : Extensions used by Wikimedia - Upcoming.
  • Une fois que l'extension est déployée sur n'importe quel wiki de production Wikimedia, elle doit être ajoutée à l'un des autres groupes Extensions utilisées par Wikimedia - * : Main pour les extensions utilisées sur tous les wikis, ou qui sont autrement très importantes; Advanced pour les utilisateurs avancés ou pour les extensions qui ne fonctionnent que sur certains wikis; et ainsi de suite. Les fichiers de messages API et les extensions qui sont uniquement destinés aux personnes hautement techniques doivent être dans le groupe Technique.
• filtrage du déploiement et drapeaux de fonctionnalité - La Fondation Wikimedia gère près d'un millier de wikis dans des centaines de langues. Lorsque nous déployons du code sur notre grappe, nous activons les extensions wiki par wiki avec des configurations souvent différentes pour chacun d'eux. Les extensions doivent avoir des drapeaux pour les fonctionnalités (par exemple, wgMaxGeoSearchRadius) pour activer ou désactiver un comportement particulier ou pour configurer une partie de l'extension, lorsque cela a un sens. Lorsque les extensions sont déployées, elles seront protégée derrière une variable de configuration globale spécifique à Wikimedia, telle que wmgUseEventLogging. Ceci permet de déployer l'extension sur un sous ensemble de wikis (par exemple test et test2) sans impacter l'ensemble des wikis. Chercher les références dans CommonSettings.php et InitialiseSettings.php qui sont très fournis.
• tests unitaires - Permettez que votre code puisse être testé automatiquement. Différentes parties du code nécessitent d'être testées différemment. Consulter en particulier Tests unitaires PHP et Tests unitaires JavaScript .
• schéma de base de données - Voir Règles de la base de données MediaWiki . Si votre code nécessite de modifier le schéma (par exemple ajouter une nouvelle colonne à une table existante) soit pour le noyau, soit pour une extension, gardez à l'esprit que le changement du schema ne peut arriver que des années plus tard sur la grappe Wikimedia. Eviter de modifier le schéma chaque fois que cela est possible.
• compatibilité - Votre extension doit être compatible avec toutes les extensions déployées sur la grappe Wikimedia.
• héberger une version de test - Les projets de Cloud VPS peuvent être utilisés pour héberger les wikis de test avec votre extension installée pour effectuer les tests et les démonstrations. Voir le guide de démarrage des services du Cloud pour plus d'informations.
• relectures du code - Vous devez travailler en étroite collaboration avec les developpeurs MediaWiki de confiance et les permanents (idéalement, les maintaineurs du noyau ou des extensions qui ont déjà été déployées sur les sites Wikimedia) durant tout le processus de dévelopment et de déploiement, afin de vous assurer que vous êtes familier avec les besoins particuliers et les habitudes pour écrire du code Wikimedia déployé. Si vous ne disposez pas de développeur particulier, demandez-en sur IRC ou sur les listes de diffusion des développeurs . Toutes les extensions déployées par Wikimedia et celles qui sont en train d'être déployées doivent suivre les Règles des privilèges Gerrit .

Une fois les étapes ci-dessus réalisées, attendez le support de la communauté pour votre idée :

• Le soutien communautaire peut être démontré en organisant une discussion active sur la nécessité de l'extension sur un wiki et en documentant les réponses. En l'absence de support communautaire actif, le support peut être construit avec les discussions et les propositions.
• Publiez votre idée sur la liste de diffusion de wikitech-l pour obtenir les commentaires des développeurs expérimentés et de Wikimedia. Les lecteurs peuvent vous indiquer une autre extension déjà en usage et dont la fonctionnalité duplique ce que vous voulez, ou qui pourrait facilement être étendue pour faire ce que vous désirez. Dans ce cas, vous devez utiliser Git pour travailler sur l'extension qui est déjà utilisée.
• Communiquez vos idées et vos plans aux wikis concernés pour obtenir à la fois un soutien, des suggestions et d'autres commentaires.
• Pour rendre les étapes ci-dessous plus faciles et plus rapides pour les relecteurs, vous êtes aussi encouragé à créer un rôle MW-Vagrant pour l'extension.

Si vous avez bien suivi les conseils ci-dessus et les commentaires des premiers examinateurs, vous devriez avoir moins de problèmes avec les prochaines étapes.

Préparer le déploiement

1. Créer une tâche de suivi du déploiement de la production dans Phabricator (pour les projets #Wikimedia-Extension-setup et #Wikimedia-Extension-Review-Queue) pour avoir une extension en file d'attente de relecture. Cette tâche ne doit concerner que le déploiement uniquement. Tout problème qui bloque le déploiement doit être une sous-tâche (listée dans la dépendance des tâches) qui bloque la tâche parent.
2. Votre bogue de traçabilité du déploiement doit pointer sur le consensus communautaire du wiki (et (ou) sur le support (ou le souhait) communautaire) pour que l'extension soit installée sur un wiki particulier si nécessaire.
3. Demander et intégrer les commentaires des revues suivantes. Ces éléments peuvent être inclus dans une liste de contrôle de la description de la tâche de suivi du déploiement de production (par exemple phab:T190716) ou comme sous-tâches de la tâche de suivi du développement de la production. Noter aussi qu' aucune revue listée ci-dessous est une nécessité absolue pour le déploiement de la production et qu' aucun ordre particulier n'est imposé pour les revues.
   • Une relecture par le propriétaire du produit pour le domaine concerné, le cas échéant. Si vous n'êtes pas sûr de la personne, essayez de contacter différentes équipes d'ingénieurs des branches Produits ou Technologie pour plus d'informations et d'entraide.
   • Une revue de l'architecture, si nécessaire.
   • Une revue des fonctionnalités bêta , si votre extension ajoute une fonctionnalité bêta.
   • Une revue de sécurité de l'application  : pour faire la demande créez une tâche de revue de la sécurité d'application et déclarez-la en tant que sous-tâche de la tâche de suivi du déploiement de la production (via Edit Task dans le coin supérieur droit). Une revue non favorable sur la sécurité peut être un point bloquant pour le déploiement de la production en fonction des détails de la demande et de ses résultats.
   • Une revue de sécurité pour toutes les dépendances externes devant être ajoutées à mediawiki/vendor. Voici une liste de base que l'équipe Securité vérifie typiquement lors de la revue du code tiers (ou celui des fournisseurs).
   • Une revue des performances . Typiquement cette revue n'est pas bloquante pour le déploiement de la production.
   • Si vous avez des raisons pour demander une revue de la base de données, créez une demande dans Phabricator.
   • IMPORTANT: tout problème sérieux (comme le blocage) identifié au cours des revues signalées précédemment doit être corrigé avant toute tentative de déploiement du code en production.
4. Demander le déploiement sur le Bêta Cluster . Voir la section Deploiement sur cluster bêta pour plus d'informations. Alors qu'il est très fortement recommandé d'avoir réalisé la revue sur la sécurité du produit avant le déploiement sur le beta cluster, le calendrier des différents projets et la nature de ces projets peut être incompatible avec la revue. Dans ce cas, le mieux est de discuter les déploiements proposés sur le beta cluster avec l'équipe Securité en dehors de toute demande de revue. Avoir un plan de maintenance à long terme approprié pour la base de code qui ne dépende pas des bénévoles individuels a souvent été un obstacle à la réussite de la revue de la sécurité de l'application.
5. Assurez-vous que l'extension est branchée automatiquement par make-wmf-branch.
   • IMPORTANT: Ne pas passer la revue de sécurité de manière satisfaisante est bloquant pour cette étape.
   • IMPORTANT: Faites-le tôt ! Idéalement, au moins trois semaines avant la date de déploiement cible, pour vous assurer que votre extension est présente sous forme de sous-module dans les branches requises. (Le sous-module d'extension doit être présent dans toutes les branches actuellement exécutées sur le cluster, sinon le constructeur du cache des traductions échouera).
6. Demander une date et une heure de déploiement dans la tâche de suivi du déploiement pour qu'il soit ajouté au calendrier du déploiement.
   • Vous (la ou les personnes qui gèrent ou qui ont demandé cela) doivent être en ligne (sur IRC dans #wikimedia-operations ^connecter) et disponibles pendant le déploiement pour répondre à tout problème pouvant survenir.

Cette liste décrit une procédure générale à suivre, y compris les exigences à respecter, mais elle ne constitue pas un processus. En particulier, l'activité de livraison d'une nouvelle extension en production n'a pas de propriétaire au niveau WMF, ce qui peut rendre difficile la recherche des revues pour les correctifs connexes. En cas de problèmes, il est recommandé de trouver des personnes (voir ajouter des relecteurs dans Gerrit ). Les développeurs sont informés que ouvrir des tâches sur Phabricator et attendre quelqu'un y prête attention n'est pas suffisant. Voir l'explication de Martin Urbanec sur phab:T61245#9152895.

Déployer sur un bêta cluster

Avant d'activer une nouvelle extension en production, elle doit être testée sur le cluster Beta. Voici les étapes nécessaires pour déployer et activer une nouvelle extension sur Bêta. (Si votre extension comporte plus d'étapes ou de dépendances, par exemple sur Wikibase, assurez-vous de vérifier avec quelqu'un avant de déployer).

Procédure

1. Ajoutez le nouveau sous-module d'extension au dépôt git mediawiki/extensions s'il n'y est pas déjà. Voir un exemple. Cela résultera en un déploiement du code (non utilisé) sur le cluster bêta.
2. Placez la configuration pour l'intégration continue de votre extension dans la section Production de Wikimedia, ajoutez le modèle de tâche in-wikimedia-production, et assurez-vous qu'il a et qu'il passe toutes les tâches attendues pour le code de production. Voir un exemple.
3. Ajoutez votre extension à l'outil de diffusion json make-wmf-branch au moins deux semaines avant votre date cible pour l'activation sur le cluster bêta. Il ajoutera l'extension en tant que sous-module du noyau Mediawiki lorsque la branche hebdomadaire de déploiement sera coupée, et que le code sera déployé (non utilisé) en production (voir l'explication à l'étape suivante). Voir un exemple.
4. Ajouter votre extension à extension-list. Voir un exemple. Ceci nécessite que le code soit présent sur chaque branche exécutée en production, depuis que extension-list est utilisé pour construire la base de données CDB pour les fichiers i18n à la fois pour Beta et pour la production.
5. Ajouter votre variable de configuration de l'extension à InitialiseSettings.php et initialisez-la par défaut à false. Voir un exemple.
6. Ajoutez votre variable de configuration d'extension (comme dans l'étape précédente) à InitialiseSettings-labs.php et initialisez-la à true sur les wikis du Beta Cluster sur lesquels vous voulez qu'elle figure. Vous voudrez peut-être le désactiver sur loginwiki (qui ne possède pas la plupart des extensions). Voir un exemple.
7. Charger votre extension dans CommonSettings-labs.php. Voir un exemple.

Notes

Le cluster Beta utilise le même répertoire wmf-configuration dans le dépôt operations/mediawiki-config que la production, mais en plus les serveurs du cluster Beta chargent les fichiers InitialiseSettings-labs.php et CommonSettings-labs.php afin que vous puissiez avoir des paramètres qui ne s'appliquent uniquement qu'au cluster Beta. Autres informations sur ces fichiers de configuration). Lors des tests sur Beta Cluster avant la production, ceux-ci peuvent redéfinir wmgUseMyExtension, en le mettant à true sur un ou plusieurs wikis du Beta Cluster. (Une fois que votre extension est utilisée sur le ou les wikis de production du Beta Cluster, vous pouvez probablement supprimer les redéfinitions de -labs.php).

Le cluster bêta exécute le code de la branche principale de Git. Vous devriez fusionner le code dans la branche principale le plus tôt et le plus souvent possible afin de l'exercer au maximum sur le cluster bêta avant qu'il ne soit publié au grand public. Si vous avez des questions particulières sur le Bêta Cluster, vous pouvez envoyer vos courriels à la liste de diffusion de l'assurance qualité ou demander à #wikimedia-releng ^connecter sur IRC .

Les habillages (skins) suivent le même processus (mais dans le répertoire mediawiki/skins).

Après le déploiement en production

• Mettre à jour votre page Extension:My Extension sur mediawiki.org en ajoutant le modèle {{OnWikimedia}} .

Voir aussi

Présentation de Roan Kattouw sur la sécurité.

• analyse de la file des projets
• Requests for comment – un endroit pour discuter des grandes idées de projet piur MediaWiki
• How to deploy code#Case 1d: new extension – détails du déploiement d'une nouvelle extension sur la grappe Wikimedia
• Demander la modification des paramètres du wiki et Limites de la modification des paramètres