Ce document explique comment créer un plug-in. Bien que le processus décrit soit destiné à créer des plug-ins propriétaires, vous pouvez l'utiliser comme guide pour créer des plug-ins tiers.
Pour en savoir plus sur les plug-ins, consultez la section Plug-ins.
Pour une présentation rapide de la création d'un plug-in, consultez notre présentation "How to Build a Plugin" (2021) (Comment créer un plug-in).
Propriétaires et tiers
L'utilisateur cible d'un plug-in est un développeur qui trouve et utilise le plug-in via npm.
Les plug-ins propriétaires sont pris en charge par l'équipe Blockly et publiés sous le champ d'application @blockly sur npm. Ils sont conçus pour être utilisés dans un large éventail d'applications Blockly. Ils sont stables et faciles à utiliser. Ils sont stockés dans blockly-samples. Un champ permettant de régler la vitesse du moteur peut être utilisé dans de nombreux projets de robotique et constitue un bon candidat pour un plug-in propriétaire.
Les plug-ins tiers sont gérés et publiés de manière indépendante. Ils peuvent être plus complexes, plus expérimentaux ou ciblés sur une gamme plus restreinte d'applications Blockly. Un champ permettant de modifier un objet spécifique défini par le schéma de votre base de données est préférable en tant que plug-in tiers.
Critères first party
Les plug-ins propriétaires doivent respecter les conditions suivantes:
- Fonctionner sur toutes les principales plates-formes, sauf si l'équipe Blockly vous accorde une exemption.
- Chrome, Firefox, Safari, Edge
- disposer d'un auteur disposé à gérer les bugs pendant la première année ;
- Ne pas modifier Blockly.
- Avoir une API clairement définie et documentée.
- N'appelez pas de fonctions privées ou de package à partir du noyau Blockly, sauf si l'équipe Blockly vous en accorde une exemption.
- Vous pouvez remplacer les fonctions de package sur une sous-classe que vous définissez.
- Si vous souhaitez une exemption, envoyez-nous une demande dans un problème sur blockly-samples.
- Effectuer des tests
Procédure
Les plug-ins passent par quatre étapes: suggestion, discussion, implémentation et publication.
Suggestion
Un plug-in commence sous la forme d'une suggestion. Vous pouvez suggérer un plug-in en créant un problème avec le modèle Demande de fonctionnalité.
Découvrez comment envoyer une demande de fonctionnalité.
En plus des informations de base sur la demande de fonctionnalité, une suggestion de plug-in doit inclure les éléments suivants:
- L'API que le plug-in exposerait.
- API à ajouter ou à modifier dans le noyau de Blockly pour prendre en charge le plug-in.
- Des captures d'écran, des GIF ou des maquettes si le plug-in inclut des fonctionnalités d'interface utilisateur
- Explication de la raison pour laquelle il doit s'agir d'un plug-in first party plutôt que d'un plug-in tiers.
L'équipe Blockly examine les suggestions au fur et à mesure qu'elles sont envoyées, et clôture le problème ou accepte qu'il s'agisse d'un bon plug-in propriétaire.
Discussion
Ensuite, un plug-in passe à la phase de discussion. Cette phase comprend les éléments suivants:
- Clarification de la fonctionnalité souhaitée.
- Clarification de l'API du plug-in.
- Planifier l'implémentation
- Planifier les tests
- Discussion sur les modifications apportées à l'API dans Blockly
- Divisez les grands plug-ins en étapes d'implémentation.
- Nom du plug-in, conformément à nos conventions d'attribution de noms.
- Vérifier que tous les critères propriétaires seront remplis.
Cette discussion se produit généralement sur le problème GitHub. Plus le champ d'application du plug-in est restreint, plus la phase de discussion peut être rapide. Les plug-ins plus volumineux peuvent attirer l'attention de la communauté et susciter des opinions tranchées sur la solution appropriée. Si c'est le cas pour votre problème, félicitations ! Vous avez trouvé un sujet qui intéresse les gens.
L'objectif est qu'à la fin de la phase de discussion, toutes les décisions de conception majeures aient été prises et qu'une liste claire des étapes d'implémentation soit disponible. Les deux doivent être documentés dans les commentaires sur le problème.
Au cours de la discussion, nous pouvons décider qu'un plug-in doit être un plug-in tiers et ne pas être publié dans le champ d'application @blockly. Dans ce cas, nous vous expliquerons pourquoi et nous clôturerons le problème.
Une fois la discussion terminée, un membre de l'équipe Blockly indique qu'elle est prête à être implémentée.
Implémentation
Les étapes d'implémentation sont les suivantes:
- Exécution de
npx @blockly/create-packagepour configurer le plug-in et son répertoire à partir d'un modèle. En savoir plus - Implémentation de la logique de base du plug-in.
- Implémentation d'une UI, si nécessaire.
- Test du plug-in à l'aide de Mocha.
- Documentation du plug-in, y compris du
README.
Si l'implémentation d'un plug-in suggéré a été approuvée et que vous souhaitez y travailler, commentez le problème et demandez si des contributions sont toujours possibles.
L'implémentation peut être effectuée par plusieurs contributeurs en parallèle. Vous pouvez implémenter un plug-in de manière collaborative sur votre propre fork ou via des demandes d'extraction sur ce dépôt. Si vous souhaitez collaborer sur un plug-in de ce dépôt, demandez à l'équipe Blockly de créer une branche de fonctionnalité pour vous.
Les plug-ins doivent être ajoutés au fichier gh-pages/index.md dans la branche master de blockly-samples. Ils apparaîtront alors sur notre site des plug-ins. Les plug-ins propriétaires doivent pointer vers leur page de test. Vous pouvez également ajouter des plug-ins tiers à cette page. Ils peuvent rediriger vers un lien de votre choix, comme une démonstration hébergée ou la page npm.
Publication
Enfin, la publication. L'équipe Blockly utilise Lerna pour gérer le contrôle des versions et la publication de tous les plug-ins.
Chaque jeudi, les plug-ins qui ont changé depuis leur dernière version sont publiés. Si vous avez besoin que la modification soit publiée plus tôt, veuillez le préciser dans votre demande de tirage.
Le site des extensions est également mis à jour chaque fois qu'une extension est publiée.
Les plug-ins qui ne sont pas prêts à être publiés doivent être marqués private dans leur package.json. Cela peut se produire si un plug-in s'appuie sur une modification non encore publiée dans le noyau Blockly. Core Blockly est publié la dernière semaine de chaque trimestre (une fois tous les trois mois).