Adicionar um plug-in

Este documento discute 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 sobre como criar um plug-in, consulte nosso Como criar um plug-in (2021).

Próprios x de terceiros

O usuário de destino 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 gama de aplicativos do Blockly e são estáveis e fáceis de usar. Elas são armazenadas no 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 direcionados a um intervalo mais estreito 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:

• Funciona em todas as principais plataformas, a menos que uma isenção seja concedida pela equipe do Blockly.
  • Chrome, Firefox, Safari, Edge
• Ter um autor disposto a lidar com bugs durante o primeiro ano.
• Não monkeypatch o Blockly.
• Tenha uma API claramente definida e documentada.
• Não chame funções particulares ou de pacote do núcleo do Blockly, a menos que receba uma isenção da equipe do Blockly.
  • É permitido substituir as funções do pacote em uma subclasse definida.
  • Se você quiser uma isenção, peça em um problema no blockly-samples.
• Fazer 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 de Solicitação de recurso.

Saiba como escrever uma solicitação 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 vai expor.
• APIs que precisam ser adicionadas ou alteradas no núcleo do Blockly para oferecer suporte ao plug-in.
• Capturas de tela, GIFs ou mockups, 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 plug-in de terceiros.

A equipe do Blockly analisa as sugestões conforme elas chegam e encerra 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 da API do plug-in.
• Planejamento da implementação.
• Planejar testes.
• Discussão sobre as mudanças na API no núcleo do Blockly.
• Dividir plugins grandes em etapas de implementação.
• Nomeação 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 com você, parabéns! Você encontrou algo que as pessoas consideram importante.

O objetivo é que, ao final da fase de discussão, todas as principais decisões de design sejam tomadas e que haja uma lista clara das etapas de implementação. Ambos precisam ser documentados nos 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 for concluída, um membro da equipe do Blockly vai notar que ela está pronta para ser implementada.

Implementação

As etapas de implementação incluem:

• Execução de npx @blockly/create-package para configurar o plug-in e o diretório usando um modelo. Saiba mais...
• Implementar a lógica principal do plug-in.
• Implementar uma interface, se necessário.
• Teste do 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. É possível implementar um plug-in de forma colaborativa no seu próprio fork ou por meio de solicitações de envio para este repositório. Se você quiser colaborar em um plug-in neste repositório, peça para a equipe do Blockly criar uma ramificação de recursos 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 próprios precisam apontar para a página de teste. Plugins de terceiros também podem ser adicionados a essa página e podem apontar para um link escolhido pelo proprietário, como uma demonstração hospedada ou a página npm.

Publicação

Por fim, publicação. A equipe do Blockly usa o Lerna para gerenciar a versão e a publicação de todos os plug-ins.

Todas as quintas-feiras, os plug-ins que foram alterados desde a última versão são publicados. Se você precisar que uma mudança seja publicada mais cedo, mencione isso na sua pull request.

O site de plug-ins também é atualizado sempre que plug-ins são publicados.

Os plug-ins que não estão 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).