Adicionar um plug-in

Este documento explica como criar um novo plug-in. Embora o processo descrito seja para criar plug-ins próprios, você pode usá-lo como uma diretriz para criar plug-ins de terceiros.

Para uma visão geral dos plug-ins, consulte Plug-ins.

Para uma introdução rápida à criação de um plug-in, assista à nossa palestra Como criar um plug-in (2021).

Dados próprios x dados de terceiros

O usuário-alvo de um plug-in é um desenvolvedor que encontra e usa o plug-in pelo npm.

Os plug-ins próprios são compatíveis com a equipe do Blockly e publicados no escopo @blockly no npm. Eles foram projetados para serem usados em uma ampla variedade de aplicativos do Blockly e são estáveis e fáceis de usar. Eles são armazenados em blockly-samples. Um campo para definir a velocidade do motor pode ser usado em muitos projetos de robótica e é um bom candidato para um plug-in próprio.

Os plug-ins de terceiros são mantidos e publicados de forma independente. Eles podem ser mais complexos, mais experimentais ou segmentados para um intervalo mais restrito de aplicativos do Blockly. Um campo para editar um objeto específico definido pelo esquema do banco de dados é melhor como um plug-in de terceiros.

Critérios próprios

Os plug-ins próprios precisam atender a estes requisitos:

• Funcionar em todas as principais plataformas, a menos que o time do Blockly conceda uma isenção.
  • Chrome, Firefox, Safari, Edge
• Ter um autor disposto a lidar com bugs no primeiro ano.
• Não faça monkeypatch no Blockly.
• Ter uma API claramente definida e documentada.
• Não chame funções particulares ou de pacote do núcleo do Blockly, a menos que a equipe do Blockly conceda uma exceção.
  • É permitido substituir funções de pacote em uma subclasse definida.
  • Se quiser uma isenção, peça em um problema no repositório blockly-samples.
• Ter testes.

O processo

Os plug-ins passam por quatro etapas: sugestão, discussão, implementação e publicação.

Sugestão

Um plug-in começa como uma sugestão. Para sugerir um plug-in, crie um novo problema com o modelo Solicitação de recurso. Para mais informações, leia sobre como escrever um pedido de recurso.

Além das informações básicas da solicitação de recurso, uma sugestão de plug-in precisa incluir:

• A API que o plug-in exporia.
• APIs que precisam ser adicionadas ou mudadas no Blockly principal para oferecer suporte ao plug-in.
• Capturas de tela, GIFs ou simulações se o plug-in incluir recursos de interface.
• Uma explicação de por que ele precisa ser um plug-in próprio em vez de um de terceiros.

A equipe do Blockly analisa as sugestões à medida que elas chegam e fecha o problema ou concorda que seria um bom plug-in próprio.

Discussão

Em seguida, um plug-in entra na fase de discussão. Esta fase inclui:

• Esclarecimento da funcionalidade desejada.
• Esclarecimento sobre a API do plug-in.
• Planejamento da implementação.
• Planejamento de testes.
• Discussão sobre mudanças na API no Blockly principal.
• Dividir plug-ins grandes em etapas de implementação.
• Nomenclatura de plug-ins, com base nas nossas convenções de nomenclatura.
• Confirmar que todos os critérios próprios serão atendidos.

Essa discussão geralmente acontece no problema do GitHub. Quanto menor o escopo do plug-in, mais rápida será a fase de discussão. Plugins maiores podem atrair a atenção da comunidade e opiniões fortes sobre a solução certa. Se isso acontecer na sua edição, parabéns! Você encontrou algo que as pessoas se importam.

O objetivo é que, ao final da fase de discussão, todas as principais decisões de design tenham sido tomadas e haja uma lista clara de etapas de implementação. Ambos precisam ser documentados em comentários sobre o problema.

Durante a discussão, podemos decidir que um plug-in precisa ser de terceiros e não ser publicado no escopo @blockly. Nesse caso, vamos explicar o motivo e encerrar o problema.

Quando a discussão é concluída, um membro da equipe do Blockly observa que ela está pronta para ser implementada.

Implementação

As etapas de implementação incluem:

• Executar npx @blockly/create-package para configurar o plug-in e o diretório dele com base em um modelo. Saiba mais...
• Implementar a lógica principal do plug-in.
• Implementar uma interface, se necessário.
• Testar o plug-in usando o Mocha.
• Documentar o plug-in, incluindo o README.

Se um plug-in sugerido foi aprovado para implementação e você quer trabalhar nele, comente sobre o problema e pergunte se ele ainda está aberto para contribuições.

A implementação pode ser feita por vários colaboradores em paralelo. Você pode implementar um plug-in de forma colaborativa no seu próprio fork ou por solicitações de envio para este repositório. Se quiser colaborar em um plug-in neste repositório, peça à equipe do Blockly para criar uma ramificação de recurso para você.

Os plug-ins precisam ser adicionados ao arquivo gh-pages/index.md na ramificação master do Blockly Samples. Isso fará com que eles apareçam no nosso site de plug-ins. Os plug-ins internos precisam apontar para a página de teste. Também é possível adicionar plug-ins de terceiros a essa página, que podem apontar para um link escolhido pelo proprietário, como uma demonstração hospedada ou a página do npm.

Publicação

Por fim, publicação. A equipe do Blockly usa o Lerna (link em inglês) para gerenciar o controle de versões e a publicação de todos os plug-ins.

Toda quinta-feira, os plug-ins que mudaram desde a última versão são publicados. Se você precisar que uma mudança seja publicada antes, informe isso na sua solicitação de pull.

O site de plug-ins também é atualizado sempre que um plug-in é publicado.

Os plug-ins que não estiverem prontos para publicação precisam ser marcados como private no package.json. Isso pode acontecer se um plug-in depender de uma mudança ainda não publicada no núcleo do Blockly. O Core Blockly é publicado na última semana de cada trimestre (uma vez a cada três meses).