Ce document explique comment créer un plug-in. Bien que le processus décrit concerne la création de plug-ins propriétaires, vous pouvez l'utiliser comme guide pour créer des plug-ins tiers.
Pour obtenir une présentation des plug-ins, consultez Plug-ins.
Pour une présentation rapide de la création d'un plug-in, consultez notre conférence sur la création d'un plug-in (2021).
Données first party et third party
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 compatibles avec l'équipe Blockly et publiés dans le champ d'application @blockly sur npm. Ils sont conçus pour être utilisables dans un large éventail d'applications Blockly, et sont stables et faciles à utiliser. Ils sont stockés dans blockly-samples. Un champ permettant de définir la vitesse du moteur pourrait ê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 cibler un éventail plus restreint 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 plus adapté à un plug-in tiers.
Critères first party
Les plug-ins propriétaires doivent respecter les exigences suivantes :
- Fonctionner sur toutes les plates-formes principales, sauf si l'équipe Blockly accorde une exemption.
- Chrome, Firefox, Safari, Edge
- Avoir un auteur prêt à gérer les bugs pendant la première année.
- Ne modifiez pas Blockly.
- Avoir une API clairement définie et documentée.
- N'appelez pas de fonctions privées ou de package à partir du cœur de Blockly, sauf si l'équipe Blockly vous a accordé une dérogation.
- Il est autorisé de remplacer les fonctions de package sur une sous-classe que vous définissez.
- Si vous souhaitez bénéficier d'une exemption, demandez-la dans un problème sur blockly-samples.
- Tests
Procédure
Les plug-ins passent par quatre étapes : suggestion, discussion, implémentation et publication.
Suggestion
Un plug-in commence par être une suggestion. Vous pouvez suggérer un plug-in en créant un problème avec le modèle Feature Request (Demande de fonctionnalité). Pour en savoir plus, consultez Rédiger 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 cœur de Blockly pour prendre en charge le plug-in.
- Captures d'écran, GIF ou maquettes si le plug-in inclut des fonctionnalités d'UI.
- Une explication de la raison pour laquelle il devrait s'agir d'un plug-in propriétaire plutôt que d'un plug-in tiers.
L'équipe Blockly examine les suggestions à mesure qu'elles arrivent et ferme le problème ou convient qu'il s'agirait 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 Core.
- Diviser les grands plug-ins en étapes d'implémentation.
- Nom du plug-in, basé sur nos conventions d'attribution de noms.
- Confirmer que tous les critères propriétaires seront respectés.
Cette discussion a généralement lieu dans le problème GitHub. Plus le champ d'application du plug-in est petit, 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 bonne solution. Si cela se produit pour votre problème, félicitations ! Vous avez trouvé un sujet qui intéresse les utilisateurs.
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 du 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 que la fonctionnalité est prête à être implémentée.
Implémentation
Voici les étapes d'implémentation :
- Exécution de
npx @blockly/create-packagepour configurer le plug-in et son répertoire à partir d'un modèle. En savoir plus - Implémenter la logique de base du plug-in.
- Implémenter une UI, si nécessaire.
- Tester le plug-in à l'aide de Mocha
- Documenter le plug-in, y compris le
README.
Si un plug-in suggéré a été approuvé pour l'implémentation et que vous souhaitez travailler dessus, commentez le problème et demandez s'il est toujours ouvert aux contributions.
L'implémentation peut être effectuée en parallèle par plusieurs contributeurs. 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 dans 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 Web des plug-ins. Les plug-ins propriétaires doivent pointer vers leur page de test. Des plug-ins tiers peuvent également être ajoutés à cette page et peuvent pointer vers un lien au choix de leur propriétaire, comme une démo hébergée ou la page npm.
Publication
Enfin, la publication. L'équipe Blockly utilise Lerna pour gérer le versionnage et la publication de tous les plug-ins.
Tous les jeudis, les plug-ins qui ont été modifiés depuis leur dernière version sont publiés. Si vous avez besoin qu'une modification soit publiée plus tôt, veuillez l'indiquer dans votre demande d'extraction.
Le site des plug-ins est également mis à jour chaque fois que des plug-ins sont publiés.
Les plug-ins qui ne sont pas prêts à être publiés doivent être marqués comme private dans leur package.json. Cela peut se produire si un plug-in s'appuie sur une modification de core Blockly qui n'a pas encore été publiée. Core Blockly est publié la dernière semaine de chaque trimestre (une fois tous les trois mois).