En este documento, se explica cómo crear un complemento nuevo. Si bien el proceso que se 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 conferencia sobre cómo compilar un complemento (2021).
Datos propios en comparación con datos de terceros
El usuario objetivo de un complemento es un desarrollador que lo encuentra y lo usa a través de npm.
El equipo de Blockly admite los complementos propios y los publica en el
alcance @blockly en npm. Están diseñados para poder usarse 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 puede 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 segmentados para un rango más reducido de aplicaciones de Blockly. Un campo para editar un objeto específico definido por el esquema de tu base de datos es mejor como complemento de terceros.
Criterios propios
Los complementos propios deben cumplir con estos requisitos:
- Funciona en todas las plataformas principales, a menos que el equipo de Blockly le otorgue una exención.
- Chrome, Firefox, Safari y Edge
- Tener un autor que esté dispuesto a controlar los errores durante el primer año
- No monkeypatch Blockly.
- Tener una API documentada y definida con claridad
- No llames a funciones privadas ni 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, envíanos un problema en blockly-samples.
- Pueden incluir pruebas.
El proceso
Los complementos pasan por cuatro etapas: sugerencia, discusión, implementación y publicación.
Sugerencia
Un complemento comienza como una sugerencia. Para sugerir un complemento, crea un problema nuevo con la plantilla Feature Request.
Obtén información para 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 Blockly principal para admitir el complemento.
- Capturas de pantalla, GIFs o maquetas si el complemento incluye funciones de la IU
- Una explicación de por qué debe ser un complemento propio en lugar de uno 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.
- Planifica la implementación.
- Planificar las pruebas
- Discusión 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 nombres
- Confirmar que se cumplirán todos los criterios propios
Por lo general, esta discusión se realiza en el problema de GitHub. Cuanto más pequeño sea el alcance del complemento, más rápida será la fase de debate. Los complementos más grandes pueden atraer la atención de la comunidad y opiniones firmes sobre la solución correcta. Si esto sucede con tu problema, felicitaciones. Encontraste algo que a las personas les importa.
El objetivo es que, al final de la fase de debate, se hayan tomado todas las decisiones de diseño principales y haya una lista clara de los pasos de implementación. Ambas deben documentarse en los comentarios sobre el problema.
Durante el debate, es posible que decidamos que un complemento debe ser de terceros y no debe publicarse en el alcance de @blockly. En ese caso, te explicaremos
el motivo y cerraremos el problema.
Cuando finaliza la discusión, un miembro del equipo de Blockly señala que está listo para implementarse.
Implementación
Estos son los pasos de implementación:
- Ejecutar
npx @blockly/create-packagepara configurar el complemento y su directorio desde una plantilla Más información… - Implementa la lógica principal del complemento.
- Implementar una IU, si es necesario
- Prueba el complemento con Mocha.
- Documentar el complemento, incluido
README
Si se aprobó un complemento sugerido para su implementación y quieres trabajar en él, comenta el problema y pregunta si aún está abierto para 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 apuntar a su página de prueba. También se pueden agregar complementos de terceros a esta página y pueden apuntar a un vínculo que elija su propietario, como una demostración alojada o la página de npm.
Publicación
Por último, publicación. El equipo de Blockly usa Lerna para gestionar 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 un cambio se publique antes, toma nota de esto 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 que aún no se publicó en Blockly principal. Core Blockly se publica en la última semana de cada trimestre (una vez cada tres meses).