Todos os grandes projetos são criados com base no feedback dos usuários. O Blockly usa problemas do GitHub para acompanhar o feedback. Nesta página, detalhamos como escrever um problema que seja fácil de ler e responder para um desenvolvedor, o que aumenta a probabilidade de que seu relatório de bug/solicitação de recurso seja resolvido.
Pré-trabalho
Alguma pergunta?
Adoramos ouvir suas perguntas. Mas os problemas do GitHub não são uma mídia muito boa para eles. Se você tiver alguma dúvida, acesse nosso fórum para desenvolvedores. Se você fizer sua pergunta lá, é mais provável que receba uma resposta oportuna e completa, porque ela está cheia de desenvolvedores que usam o Blockly há anos!
Verificar se há duplicatas
Antes de começar a programar qualquer tipo de problema, é sempre bom ver se já existe um problema correspondente. Se isso acontecer, você não terá que escrever por conta própria! Portanto, antes de começar a escrever, faça algumas pesquisas sobre duplicatas ou problemas relacionados.
- Pesquisar em blockly-samples
- Pesquisar no Blockly Core
- Pesquise no fórum
Se você encontrar um problema correspondente, marque-o com um "Gostei" ou adicione um comentário detalhando suas ideias. Isso é especialmente importante para relatórios de bugs e solicitações de recursos. Se os desenvolvedores perceberem que um problema está recebendo muita atenção, é mais provável que ele seja resolvido.
Informar um bug
Então você acha que descobriu um bug? Ótimo! Adoramos ouvir relatórios de bugs, porque queremos que o projeto seja o mais estável possível. Aqui estão algumas etapas que você pode seguir para ajudar a corrigir o bug.
- Verificar se há duplicatas
- Coletar evidências
- Localizar o problema
- Solucione sua reprodução
- Sugira uma causa
- Escreva o problema
Coleta de evidências
Geralmente, quanto mais informações o bug tiver, melhor. Aqui estão alguns itens convém fornecer:
- Capturas de tela ou GIFs podem ser muito úteis se um bug causar um problema visual.
- O exemplo de código é útil se um bug afetar apenas determinados tipos de blocos ou configurações de espaços de trabalho.
- Um site hospedado é ótimo se você está com problemas para reproduzir o bug fora do seu ambiente específico.
Localizar o problema
Entre a biblioteca principal, os plug-ins, os exemplos e os codelabs, temos muito código do Blockly. Ajude-nos informando exatamente onde está o problema.
Se o problema é principal, qual é o componente? Por exemplo, pode ser um problema com a caixa de ferramentas, os controles de zoom ou os blocos da biblioteca. Seja o mais específico possível.
Se o problema estiver em amostras em blocos, descubra em qual plug-in, codelab ou exemplo ele está. Se você encontrar o mesmo bug em vários lugares, informe-nos também.
Para solidificar sua reprodução
Um bug só pode ser corrigido se for reproduzível. Portanto, antes de enviar um problema, verifique se você tem uma maneira sólida de fazer com que ele ocorra.
Você vai ter uma lista numerada de etapas que informam ao desenvolvedor como reproduzir o bug. Exemplo:
- Abra o codelab X.
- Ir para a página Y.
- Execute o código de exemplo de Z.
- Observe o mau comportamento, que é semelhante a W.
Se o problema estiver no Blockly Core, tente reproduzi-lo na playground.
Sugira uma causa
Se você acha que sabe por que o bug está acontecendo, inclua essa informação também. Novamente, seja o mais específico possível.
Escreva o problema
Chegou a hora de escrever seu relatório do bug. Selecione seu repositório:
- Bloco de núcleo
- Blockly-samples (em inglês)
Preencha todas as seções do modelo de problema, mesmo as não detalhadas aqui.
Agradecemos seu interesse em informar um bug. Bom trabalho!
A seguir
- Seu relatório de bugs é marcado automaticamente para triagem.
- O membro de plantão da equipe da Blockly analisará e poderá fazer perguntas esclarecedoras. Eles também vão adicionar rótulos, que usamos para manter nossos bugs organizados.
- O problema pode estar marcado como "Help Wanted". Nesse caso, você pode reivindicá-lo e começar a trabalhar nele.
- O problema pode ser atribuído a um membro da equipe da Blockly para correção.
- O problema pode ser marcado com um marco trimestral para indicar quando ele será concluído.
- O problema pode ser colocado no marco do Icebox, o que significa que não pretendemos
trabalhar nele em um futuro próximo.
- Isso pode acontecer com problemas de baixa frequência ou bugs com soluções alternativas conhecidas.
- Você ainda pode resolver problemas com o Iceboxing.
- O problema pode ser colocado no marco do backlog do Bug Bash, o que significa que ele não é
urgente, mas ainda queremos corrigi-lo.
- No final de cada trimestre, a equipe passa algumas semanas trabalhando em bugs extraídos do marco de backlog do Bug Bash.
- O problema pode ser movido do núcleo do Blockly para amostras blockly (ou a direção oposta), se necessário.
- O problema pode ter sido encerrado.
Solicitação de recurso
Há algo que você queira mudar para melhorar o Blockly? Você tem uma ideia de plug-in, exemplo ou codelab? Talvez já haja uma de que você goste e você tenha pensado em uma maneira de melhorá-la. Se sim, você veio ao lugar certo! Estas são as etapas para criar uma ótima solicitação de recurso que receba uma resposta.
- Verificar se há duplicatas
- Conferir os requisitos
- Reunir suas ideias
- Escreva sua solicitação de recurso.
Verifique os requisitos
Adoraríamos permitir que todas as ideias entrem neste repositório! Infelizmente, somos apenas humanos, por isso temos algumas diretrizes sobre os tipos de solicitações que atenderemos.
Aqui estão as diretrizes para cada uma das diferentes categorias de projetos:
- Bloco de núcleo
- Plug-ins
- Exemplos: mostrar como usar apenas um ou dois recursos do Blockly.
- Codelabs: mostre como concluir uma única tarefa ou implementar um único comportamento.
Mas essas regras não são rígidas. Elas servem apenas para dar uma ideia do que estamos procurando antes de você dedicar tempo para criar sua solicitação de recurso.
Se você não tiver certeza se algo se encaixa, tente postá-lo nos nossos fóruns de desenvolvedores. E lembre-se, mesmo que sua ideia não seja aceita, adoraríamos que você a criasse como um plug-in ou tutorial de terceiros.
Reúna suas ideias
Sua ideia não precisa estar 100% criada com detalhes e diagramas antes de prosseguir, mas você precisa ter uma ideia sólida do que está procurando. Aqui estão algumas boas perguntas para refletir antes de começar a escrever:
- Por que quero esse recurso?
- Este recurso resolve algum problema?
- Qual é o público-alvo deste recurso?
- Por que esse recurso os atende?
- Quais são algumas opções alternativas que podem alcançar o mesmo resultado?
Depois de descobrir isso, você estará no caminho certo para conseguir um bom pedido de recurso.
Escreva sua Solicitação de Recurso.
Agora está tudo pronto para escrever a solicitação de recurso. Selecione seu repositório:
- Bloco de núcleo
- Blockly-samples (em inglês)
Preencha todas as seções do modelo de problema, mesmo as não detalhadas aqui.
Agradecemos seu interesse em enviar uma solicitação de recurso. Bom trabalho!
A seguir
- Sua solicitação de recurso é marcada automaticamente para triagem.
- O membro de plantão da equipe da Blockly analisará e poderá fazer perguntas esclarecedoras. Eles também vão adicionar rótulos, que usamos para manter nossos bugs organizados.
- O recurso pode estar marcado como "Help Needed". Nesse caso, você pode reivindicá-lo e começar a trabalhar nele.
- O recurso pode ser atribuído a um membro da equipe do Blockly para implementação.
- A solicitação de recurso pode ser movida do núcleo do Blockly para as amostras blockly (ou a direção oposta), se necessário.
- A solicitação de recurso pode ser fechada. Nesse caso, você ainda tem a opção de implementá-la como um plug-in de terceiros.