Manuel:Développer des bibliothèques

Voici les règles pour créer, publier et gérer les bibliothèques basées sur le code initialement développé en tant que partie de MediaWiki ou d'un projet lié à Wikimedia. Certaines de ces règles sont particulières à PHP mais les autres sont générales et s'appliquent à tous les langages.

Principes

Il y a un désir croissant de séparer les bibliothèques utiles de l'application du noyau MediaWiki et de les rendre utilisables dans les projets non basés sur MediaWiki. Cette mise en bibliothèques de MediaWiki est fait dans le but d'avoir plusieurs avantages à long terme.

• Améliorer la vie des nouveaux développeurs (et des développeurs expérimentés) en organisant le code en composants simples et faciles à comprendre.
• Inverser l'inertie vers un noyau monolithique en constante expansion en encourageant les développeurs (du noyau) à développer leur travail en tant que modules réutilisables avec des interfaces clairement définies
• Commencer à rendre fiables les tests unitaires du noyau en disposant d'unités testables séparément
• Fournir une étape intermédiaire sur la voie de l'architecture axée sur les services d'une manière utile indépendamment de cet objectif
• Encourager la réutilisation et l'intégration dans un écosystème logiciel plus grand. Si nous le faisons correctement, cela permettra d'élargir notre capacité de développement en recrutant les auteurs des bibliothèques désireux de présenter leur travail parmi les dix premiers, sur un site Web.
• Partagez nos formidables bibliothèques avec d'autres personnes et encouragez-les à contribuer même s'ils ne sont pas particulièrement intéressés pour améliorer nos sites.

Pour que cette stratégie réussisse, ces bibliothèques doivent avoir leur propre vie, indépendante de MediaWiki. Il est donc important que les auteurs de ces bibliothèques aient une certaine latitude et une certaine indépendance pour réussir leur travail. Les politiques qui les entourent doivent être en grande partie dictées par le mainteneur principal de la bibliothèque, et les choix réalisés peuvent diverger de ceux du noyau MediaWiki. Notez que le mainteneur principal peut ne pas être l'auteur original de la majorité du code (ni même d'une partie quelconque), et aura la liberté de prendre des décisions indépendantes concernant la bibliothèque. L'éventail de possibilités attribué à un mainteneur est proportionnel à la quantité de commit réalisés, à la crédibilité qu'il a et au travail acharné qu'il fait sur la bibliothèque qu'il entretient.

Directives pour l'hébergement sur un dépot

• Hébergé dans Gerrit avec le miroir GitHub
• Hébergé par l'organisme Wikimedia GitHub
• Hébergé sous une autre organisation GitHub
• Hébergé dans Phabricator avec le miroir GitHub (?? sommes-nous prêts à essayer arc avec les bibliothèques ?)

La Fondation Wikimedia investira probablement dans des outils qui, à l'avenir, transféreront la relecture de code de GitHub vers des outils d'examen interne (comme Phabricator). Eventuellement cela devrait éliminer la différence entre l'hébergement du dépôt git primaire avec la Fondation Wikimedia ou GitHub. Dans l'immédiat, l'hébergement Gerrit est l'option d'hébergement par défaut, sauf dans le cas où des efforts sont faits pour attirer une part importante des contributions des développeurs externes.

N'utilisez pas de compte utilisateur GitHub individuel pour héberger les fichiers. Cela complique la relecture de code basée sur les demandes de pull pour le propriétaire du dépôt et rend difficile la gestion du dépôt par un groupe partagé.

Cela ne signifie pas qu'il faut héberger sous le compte Wikimedia spécifiquement; en fait, il peut être plus pratique d'avoir le projet sous un compte organisationnel différent spécifique au projet, comme CSSJanus.

Directives pour le nommage du dépôt

Varie probablement en fonction de l'emplacement de l'hôte. Suivez les conventions locales tant que cela est raisonnable et possible. N'ajoutez pas de préfixe « wikimedia- » au nom des dépôts. Sous Gerrit le dépôt Git doit être nommé « mediawiki/libs/<name> ».

Directives pour le suivi des problèmes

• Phabricator
• GitHub

Le suivi des problèmes de votre bibliothèque doit correspondre à votre hébergement git, afin de réduire le frictions existant entre commit et pull des demandes relatives aux problèmes et vice versa. Ainsi, les dépôts hébergés par Gerrit doivent instancier Phabricator Wikimedia et ceux hébergés par GitHub doivent utiliser le gestionnaire de problèmes embarqué dans GitHub.

Directives pour la relecture du code

La relecture du code du projet doit utiliser l'outil le plus proche associé à l'hébergement git primaire. Quel que soit le choix de la plateforme d'hébergement, la relecture du code avant la fusion et les tests unitaires sont fortement encouragés. Le comportement flagrant de l'auto-fusion devrait être vu comme aussi désastreux dans GitHub, comme il l'est généralement dans Gerrit.

Si l'hébergement principal est fait via GitHub, les modifications doivent être proposés via des demandes de pull au lieu de pousser directement sur le master. Dans la plupart des cas, les demandes de pull doivent provenir d'un fork du dépôt associé au compte GitHub de l'utilisateur. GerritHub est un service de relecture de code basé sur Gerrit qui peut être utilisé avec des dépôts hébergés sur GitHub pour les projets qui veulent utiliser Gerrit mais qui, pour une raison quelconque, ne veulent pas héberger avec Wikimedia.

Directives pour la présentation du code

Voir aussi : Points d'accès dans l'intégration continue pour les tests PHP

Nous encourageons le style MediaWiki ou PHP PSR-2, mais les choses les plus importantes sont la clareté, la cohérence et la meilleure ressemblance à ce qui est adopté par la communauté des développeurs de la bibliothèque.

Lorsque vous créez un nouveau dépôt, vous DEVEZ choisir un style de codage standard et l'appliquer avec CodeSniffer. Pointer également le guide de style dans le fichier README du projet.

Pour le style de codage MediaWiki, utilisez le paquet mediawiki/mediawiki-codesniffer.

Assurez-vous d'utiliser la dernière version de codesniffer de Mediawiki (voir packagist.org). Ne pas utiliser de version avec joker car les mises à jour doivent être faites explicitement afin d'éviter un état bloquant de la branche principale.

Pour le style de codage PSR-2, utilisez PHP CodeSniffer.

Directives pour les tests automatiques

Vous devez utiliser à la fois les tests avant et après la fusion. Les tests doivent inclure le lint de base, les tests unitaires et les vérifications du style du codage.

Gerrit

Les projets hébergés dans Gerrit Wikimedia doivent utiser Jenkins. Utiliser le point d'accès composer test. Voir les point d'accès dans l'intégration continue pour PHP pour les détails.

Une fois créé, assurez-vous de permettre également au publicateur post-fusion de générer automatiquement la documentation et la couverture de code (par exemple pour IPSet, https://doc.wikimedia.org/IPSet/ et https://doc.wikimedia.org/cover/IPSet/). Ces tâches peuvent être activées pour votre projet dans le dépôt integration/config (exemple de commit : Gerrit change 227615). En parallèle, créez une tâche dans le projet ci-config.

Directives pour créer les paquets

Les bibliothèques PHP doivent être publiées sur packagist.org. Lors de l'ajout de nouveaux paquets :

• Suivez les meilleures pratiques de composer.json et ajoutez un élément dans votre dépôt.
• Request the Packagist.org service hook in the GitHub repo to be configured by filing a task.

Instructions si vous avez les droit requis (vous êtes un propriétaire dans l'organisation Wikimedia GitHub et avez accès aux comptes Packagist mediawiki et wikimedia) :

1. Utilisez le miroir github.com pour l'URL git, ce qui permettra à composer de télécharger des archives zip du cache.
2. Soumettre le dépôt dans Packagist.org :
   • Connectez-vous à Packagist.org avec le compte Wikimedia et soumettez l'URL GitHub.
3. Assurez-vous que les comptes mediawiki et wikimedia sont les mainteneurs du paquet.

Les personnes suivantes ont accès aux différents comptes dans le cas où un paquet a besoin d'être mis à jour pour une raison quelconque :

• wikimedia: BDavis, Krinkle ...? (informations de connexion gardées dans pwstore de l'équipe SRE)
• mediawiki: ^demon, Legoktm, BDavis, Krinkle ...? (informations de connexion gardées dans pwstore de l'équipe SRE)

Les paquets distribués via Composer et Packagist doivent aussi inclure un fichier de configuration .gitattributes dans leur dépôt git qui exclut les fichiers tels que des tests et les exemples qui ne sont pas nécessaires à l'exécution du paquet généré. La bibliothèque wikimedia/RelPath est un bon exemple :

/.* export-ignore
/Doxyfile export-ignore
/composer.json export-ignore
/phpunit.xml.dist export-ignore
/build/ export-ignore
/tests/ export-ignore

Notez que composer.json doit être exclu, ce qui est un peu contre-intuitif. Le fichier composer.json qui correspond actuellement à une version donnée de votre bibliothèque sera généré par Packagist et envoyé séparément du paquet zip actuel.

Directives pour le choix de la licence

Pour quasiment tout ce qui est extrait de MediaWiki, il est probable qu'il devra être sous GPLv2 (ou ultérieur). Tous les contributeurs doivent être d'accord si quelqu'un veut changer la licence GPLv2+ (sauf pour le passage en GPLv3). La licence de la nouvelle bibliothèque doit rester clairement marquée dans les entêtes du code, et le fichier de licence complet (généralement appelé "LICENCE" ou "COPYING") doit être mis dans le nouveau projet.

Pour une bibliothèque composée entièrement de code nouveau, toute licence conforme aux Open Source Definition est susceptible d'être acceptable, mais les licences MIT, GPLv2+ et Apache License 2.0 peuvent être les plus faciles à adopter. Inclure ensemble les droits d'auteur du contributeur et les clauses d'attribution qui sont importantes pour assurer l'intégrité de la base de code du projet. Les licences Apache2 et MIT sont considérées comme plus permissives, dans le sens où elles permettent aux oeuvres dérivées d'inclure une license séparée pour les nouvelles contributions.

Directives pour la documentation

Fichier Readme

Toute bibliothèque doit avoir un fichier README.md qui décrit le projet à un haut niveau. Ce fichier doit être formaté en utilisant la syntaxe Markdown (par exemple pour les entêtes, les liens et les blocs de code) qui est communément pris en charge par la majorité des navigateurs git tout en restant lisible par l'homme.

Un bon fichier README.md doit inclure :

• Une description rapide des cas d'utilisation principaux auxquels répond la bibliothèque
• Comment installer la bibliothèque
• Comment utiliser la bibliothèque (format texte avec exemples de code si possible)
• Comment contribuer
  • Nom de la licence (GPL-2, ...)
  • Où adresser les bogues
  • Où proposer les corrections
  • Lien vers les règles de codage
  • Comment exécuter les tests
  • Où voir le résultat des tests automatiques

Documentation du code

Ajouter un pipe pour générer la documentation du code. Les choix habituels sont :

• Doxygen (pour PHP)
• JSDuck (pour JavaScript)
• Sphinx (pour Python)
• Yard (pour Ruby)

Afficher la documentation des bibliothèques existantes sur https://doc.wikimedia.org pour voir des exemples. Voir les points d'accès dans l'intégration continue pour savoir comment configurer cela.

Documentation en ligne sur le wiki

Les bibliothèques doivent avoir une courte page sur mediawiki.org qui documente leur fonction, l'historique, et les liens relatifs. Exemples (liste complete) :

• CDB
• utfnormal
• IPSet

Bootstrap d'une nouvelle bibliothèque

Les nouvelles bibliothèques nécessitent d'ajouter de nombreux fichiers communs pour pouvoir démarrer (.gitattributes, composer.json, Doxyfile, phpunit.xml, etc.). Pour faciliter la chose, il existe des outils qui permettront de démarrer l'extension à votre place.

• bibliothèques PHP : cookiecutter-library

Combinaisons usuelles

• Hébergé dans Gerrit et publié dans Packagist dans l'espace de noms wikimedia
• Hébergé dans l'organisation GitHub Wikimedia et publié sur Packagist dans l'espace de noms wikimedia.
• Hébergé dans une autre organisation GitHub et publié sur Packageist comme autre chose que Wikimedia ou Mediawiki (par exemple cssjanus).

Lorsque l'hébergement se fait dans Gerrit, le projet doit fonctionner comme tout autre projet typique sponsorisé par Wikimedia avec la relecture de code Gerrit, la traçabilité des bogues dans Phabricator et la documentation sur le wiki.

Si l'hébergement est effectué sur GitHub, le projet peut raisonnablement choisir de faire la relecture du code via des requêtes pull et héberger le traceur de bogues sur GitHub. Ce choix doit être examiné avec soin, projet par projet, car la divergence des outils de révision du code et de suivi des problèmes de la communauté Wikimedia élargie présente certains inconvénients :

• Bugwrangler n'est pas censé contrôler les problèmes de votre projet.
• Les membres de la communauté des développeurs MediaWiki vont probablement déclarer de toute manière, la présence de bogues dans votre produit dans Phabricator.
• Reporter un rapport de bogue entre votre projet et MediaWiki sera un processus plus impliquant.

Ces inconvénients peuvent diminuer avec le temps si de meilleurs robots peuvent être créés pour intégrer les deux environnements.

Héberger sous une organisation GitHub indépendante a un sens pour certains projets (CSSJanus, Wikidata, Semantic MediaWiki, ...) où il faut faire un effort pour développer une communauté indépendante et pérenne pour le projet. C'est particulièrement raisonnable si on prend le cas d'une bibliothèque comme CSSJanus qui tente d'établir un ensemble d'outils standard intercommunautaires et interlinguistes et où seulement une partie des outils recouvre ceux de l'univers Wikimedia.

Transférer un dépot existant de GitHub vers Wikimedia

• Faire un ticket dans le projet Phabricator Librarization pour demander le transfert.
• Lorsque vous êtes contacté, transférer le dépôt à l'administrateur GitHub de Wikimedia qui répond.
• L'administrateur déplacera le projet vers Wikimedia et vous donnera l'accès.

Conseils pour extraire une bibliothèque

Les détails de l'extraction d'une bibliothèque varient en fonction du code extrait et de son imbrication actuelle avec les autres classes spécifiques de MediaWiki. Dans le meilleur des cas, le code que vous voulez extraire est déjà contenu dans le répertoire includes/libs de mediawiki/core.git et donc complètement libre. Il est suggéré que le code qui n'est pas dans cet état soit progressivement mis à jour et refactorisé jusqu'à atteindre cet état.

Une fois que tout le code est dans includes/libs, les choses deviennent un peu plus claires :

1. Créer un nouveau projet en suivant le reste des instructions de cette RFC.
2. Importer le code de includes/libs dans votre nouveau projet.
   • Il doit être possible d'utiliser git filter-branch pour extraire une copie des fichiers en préservant l'historique des commit, mais cela n'est pas actuellement considéré comme une condition préalable à l'extraction. Il devrait suffire d'inclure le HEAD actuel des fichiers dans le nouveau projet et de fournir la documentation de l'origine du fichier dans le README du nouveau projet.
3. Créer un fichier composer.json dédié qui suive les meilleures pratiques pour le projet et le publier dans Packagist.
4. Marquer le dépôt pour créer une version stable.
5. Proposer une modification dans mediawiki/vendor.git pour importer la version stable de votre nouveau projet. Voir Manuel:Bibliothèques externes pour plus de détails.
6. Proposer une modification de composer.json dans mediawiki/core.git pour demander la version stable de votre nouveau projet.

Il peut également être nécessaire d'introduire les classes shim mediawiki/core.git pour fournir un pont de compatibilité arrière entre votre bibliothèque extraite et la base de code MediaWiki existante. La bibliothèque CDB fait cela pour permettre la compatibilité arrière des noms de classes ce qui ne nécessite pas l'utilisation du nouvel espace de noms Cdb\ .

Releasing a new version of a library

• Pour déterminer le numéro de version suivant, rapprochez-vous du système de version semantic
• Make sure the code is ready for release, e.g. update the readme and changelog files (example).
• signer avec GPG la balise en ajoutant -s à la commande git tag

  git tag -s v2.1.0 -m "Signed v2.1.0 release"
  

  * Vous pouvez également fournir une trace des modifications dans les notes des balises annotées
• * Puis git push --tags pour soumettre la marque.

Depending on the language of the library, you may at this point need to publish the new version to a registry, e.g. with npm publish or python3 -m twine upload dist/*. Note that this is not necessary with PHP, as Packagist is configured to listen for new git tags and auto-publish.

• Update any on-wiki documentation.
• Find all the components using the library, via LibUp: https://libraryupgrader2.wmcloud.org/library?branch=main
• If needed, update the library version in mediawiki/vendor and the relevant production components using the library, and ensure tests pass and code works as before.
• Preferably update the version in non-production components.

Après la première version

Une fois que le dépôt est démarré et que les sorties initiales ont été faites. Voici quelques étapes suivantes à considérer :

• Créer une page pour la bibliothèque ici sur mediawiki.org. Voir At-ease pour un bon exemple. Cette page doit pointer vers :
  • Code source (par exemple git.wikimedia.org ou github.com).
  • Paquet publié (par exemple sur Packagist.org ou npmjs.org).
  • Gestionnaire des problèmes (par exemple, tableau de travail de Phabricator ou GitHub Issues).
  • Documentation de l'API (par exemple doc.wikimedia.org).
• Entrez la description et l'URL pour le miroir GitHub. Particulièrement si elle est seulement recopiée sur GitHub, c'est facile à oublier. Entrez une description sur une seuleligne et entrez l'URL de la page mediawiki.org (si elle existe) ou sinon la page doc.wikimedia.org . Voir https://github.com/wikimedia/cdb et https://github.com/wikimedia/oojs pour les exemples.

Information des RFC

Appel à commentaires (RFC)

fr
Composant	General
Date de création	24 décembre 2014
Auteur(s)	BDavis (WMF)
État du document	implemented Accepted. Tim Starling (talk) 21:45, 14 Jan 2015 (UTC)

Ceci est issu de la RFC Instructions pour l'extrait, la publication et la gestion des bibliothèques. La décision a été de déplacer cette page hors de l'espace des RFC et de l'améliorer en tant que documentation.

Voir aussi

• Manuel:Bonnes pratiques pour composer.json
• RFC bibliothèques gérées par composer à utiliser sur le cluster WMF
• Library infrastructure for MediaWiki
• projet Librarization dans Phabricator
• Intégration continue/Points d'accès