En este documento, se explica cómo crear un complemento nuevo. Si bien el proceso que describe es para crear complementos propios, puedes usarlo como guía para crear complementos de terceros.
Para obtener una descripción general de los complementos, consulta Complementos.
Para obtener una introducción rápida a la creación de un complemento, consulta nuestra charla sobre cómo crear un complemento (2021).
Comparación entre los datos de origen y los de terceros
El usuario objetivo de un complemento es un desarrollador que encuentra y usa el complemento a través de npm.
El equipo de Blockly admite los complementos propios, que se publican en el alcance @blockly en npm. Están diseñados para ser utilizables en una amplia variedad de aplicaciones de Blockly, y son estables y fáciles de usar. Se almacenan en blockly-samples. Un campo para configurar la velocidad del motor se podría usar en muchos proyectos de robótica y es un buen candidato para un complemento propio.
Los complementos de terceros se mantienen y publican de forma independiente. Pueden ser más complejos, más experimentales o estar dirigidos a un rango más estrecho de aplicaciones de Blockly. Un campo para editar un objeto específico definido por el esquema de tu base de datos es mejor como un complemento de terceros.
Criterios de origen
Los complementos propios deben cumplir con estos requisitos:
- Funcionar en todas las plataformas principales, a menos que el equipo de Blockly otorgue una exención
- Chrome, Firefox, Safari y Edge
- Tener un autor que esté dispuesto a encargarse de los errores durante el primer año
- No apliques parches a Blockly.
- Tener una API claramente definida y documentada
- No llames a funciones privadas o de paquetes desde el núcleo de Blockly, a menos que el equipo de Blockly te otorgue una exención.
- Se permite anular las funciones del paquete en una subclase que definas.
- Si quieres una exención, pídenosla en un problema en blockly-samples.
- Pueden incluir pruebas.
El proceso
Los complementos pasan por cuatro etapas: sugerencia, debate, implementación y publicación.
Sugerencia
Un complemento comienza como una sugerencia. Para sugerir un complemento, crea un problema nuevo con la plantilla Solicitud de función. Para obtener más información, lee sobre cómo escribir una solicitud de función.
Además de la información básica de la solicitud de función, una sugerencia de complemento debe incluir lo siguiente:
- Es la API que expondría el complemento.
- Son las APIs que se deben agregar o cambiar en el núcleo de Blockly para admitir el complemento.
- Capturas de pantalla, GIFs o simulaciones si el complemento incluye funciones de IU
- Una explicación de por qué debería ser un complemento de origen en lugar de un complemento de terceros.
El equipo de Blockly revisa las sugerencias a medida que llegan y cierra el problema o acepta que sería un buen complemento propio.
Debate
A continuación, un complemento pasa a la fase de discusión. Esta fase incluye lo siguiente:
- Aclaración de la funcionalidad deseada
- Se aclaró la API del complemento.
- Planificación de la implementación
- Planificar las pruebas
- Debate sobre los cambios en la API de Blockly principal
- Dividir los complementos grandes en pasos de implementación
- Nombres de complementos, según nuestras convenciones de nomenclatura
- Confirmar que se cumplirán todos los criterios de origen
Por lo general, esta discusión se lleva a cabo en el problema de GitHub. Cuanto más pequeño sea el alcance del complemento, más rápido podrá ser la fase de debate. Los complementos más grandes pueden atraer la atención de la comunidad y generar opiniones sólidas sobre la solución correcta. Si esto sucede con tu problema, ¡felicitaciones! Encontraste algo que le importa a la gente.
El objetivo es que, al final de la fase de debate, se hayan tomado todas las decisiones de diseño importantes y haya una lista clara de los pasos de implementación. Ambos deben estar documentados en los comentarios del problema.
Durante el debate, es posible que decidamos que un complemento debe ser de terceros y no publicarse en el alcance de @blockly. En ese caso, explicaremos el motivo y cerraremos el problema.
Cuando finaliza la discusión, un miembro del equipo de Blockly indica que está lista para implementarse.
Implementación
Los pasos de implementación incluyen lo siguiente:
- Ejecuta
npx @blockly/create-packagepara configurar el complemento y su directorio a partir de una plantilla. Más información… - Implementar la lógica principal del complemento
- Implementar una IU, si es necesario
- Probar el complemento con Mocha
- Documentar el complemento, incluido el
README
Si se aprobó la implementación de un complemento sugerido y quieres trabajar en él, comenta el problema y pregunta si aún se aceptan contribuciones.
Varios colaboradores pueden realizar la implementación en paralelo. Puedes implementar un complemento de forma colaborativa en tu propia bifurcación o a través de solicitudes de extracción en este repositorio. Si quieres colaborar en un complemento de este repositorio, pídele al equipo de Blockly que cree una rama de funciones para ti.
Los complementos se deben agregar al archivo gh-pages/index.md en la rama master de blockly-samples. Esto hará que aparezcan en nuestro sitio de complementos. Los complementos propios deben dirigir a su página de prueba. También se pueden agregar complementos de terceros a esta página, y pueden dirigir a un vínculo que elija su propietario, como una demostración alojada o la página de npm.
Publicación
Por último, la publicación. El equipo de Blockly usa Lerna para administrar el control de versiones y la publicación de todos los complementos.
Todos los jueves, se publican los complementos que cambiaron desde su última versión. Si necesitas que se publique un cambio antes, indícalo en tu solicitud de extracción.
El sitio de complementos también se actualiza cada vez que se publican complementos.
Los complementos que no estén listos para publicarse deben marcarse como private en su package.json. Esto puede ocurrir si un complemento depende de un cambio en Blockly principal que aún no se publicó. Core Blockly se publica en la última semana de cada trimestre (una vez cada tres meses).