Usar as ferramentas

Um dos retornos de informação mais valiosos que podemos receber é o das pessoas que tentam usar as ferramentas BeeWare e descobrem que há um ponto de atrito ou um recurso ausente. É extremamente útil para nós entender as dificuldades que você pode ter ao usar as ferramentas para fins reais.

Pense na coisa que sempre quis construir e tente construí-la. Se conseguir construir o seu projeto, parabéns! Tem aquilo que sempre quis.

No entanto, se não for bem-sucedido, informe-nos sobre o que deu errado. Faltou algum recurso? A documentação é confusa ou carece de algum aspeto? Partilhar a sua experiência dá-nos uma visão útil que podemos usar para moldar o nosso processo de planeamento.

Se tiver algum problema, inicie um novo tópico de discussão, pois pode ser o início de um novo problema ou proposta de funcionalidade.

Contribuir para o uso da ferramenta

Submeter um novo problema

Submeter uma nova questão

Escrever um bom relatório de problema ou bug pode fazer toda a diferença na capacidade de solucionar um problema. Aqui está como submeter um bom relatório de bug para BeeWare.

Procurar por problemas existentes

Antes de submeter um novo problema, pesquise no índice por problemas existentes que correspondam ao seu. Se houver um problema aberto que pareça corresponder ao seu problema, adicione um comentário a esse problema com informações adicionais sobre sua experiência. Por exemplo, se estiver a ver o problema numa versão diferente do Python ou num sistema operativo diferente, essas informações adicionais podem ser úteis para determinar o impacto ou a causa de um problema.

Se encontrar um problema encerrado que parece corresponder ao seu problema, verifique se esse problema foi encerrado recentemente. Se o problema foi fechado muito recentemente, isso provavelmente significa que o bug foi corrigido e virá corrigido na próxima versão. Se o problema foi encerrado há mais de 4 meses, é provável que o que esteja a enfrentar seja um problema diferente - por mais semelhante que seja a mensagem de erro.

Se não encontrar um problema que corresponda ao que está a ver, talvez seja apropriado abrir um novo problema.

Comece com uma discussão

Antes de submeter um problema para o GitHub, considere começar com uma discussão para perguntar se o que está a acontecer é realmente um bug ou um problema com sua configuração ou processo. A menos que esteja a ver um comportamento que contradiga diretamente o comportamento documentado, provavelmente vale a pena fazer uma pergunta antes de enviar diretamente um relatório de bug. Se se verificar que encontrou um problema, um tópico de discussão pode ser facilmente transformado num problema.

Iniciar uma discussão também pode ajudar a garantir que esteja a relatar um problema no melhor lugar. Embora possa ter tido um problema ao usar BeeWare, o problema pode ser causado por um bug dum projeto diferente no ecossistema do BeeWare.

Escrever um bom relatório de bug

Se um novo problema for necessário, é importante fornecer o máximo de detalhes possível. Um bom relatório de bug inclui todas as informações potencialmente relacionadas ao bug, bem como o menor exemplo de reprodução possível.

O exemplo de reprodução deve ser o mais curto e conciso possível e, ao mesmo tempo, exibir o bug. Fornecer um exemplo enorme dificulta muito a solução de problemas, especialmente se ele depender de outras bibliotecas ou exigir um conhecimento extenso do comportamento esperado ou da lógica interna do exemplo.

Precisamos do máximo de detalhes que puder fornecer. Isso inclui, mas definitivamente não se limita a:

• A versão do seu sistema operativo - até a versão micro (por exemplo, macOS 15.7.2).
• A sua versão do Python, também até a versão micro (por exemplo, 3.14.1).
• Como instalou o Python. Descarregou-o do python.org? Usou o Homebrew? uv? pyenv? conda? Outra coisa?
• A versão específica das ferramentas BeeWare que está a usar (por exemplo, Toga 0.5.3). Se estiver a usar uma versão de desenvolvimento, qual hash do Git está a usar? Não basta dizer "o ramo principal atual", pois isso pode mudar diariamente.
• As versões específicas de outros pacotes que têm de ser instaladas para despoletar o problema. Pode incluir os resultados da execução de python -m pip freeze para fornecer esta informação.
• Se um ficheiro de relatório tiver sido gerado, o ficheiro de relatório inteiro.
• Se uma pilha de rastreio tiver sido gerado, a pilha de rastreio inteiro. Não forneça apenas a mensagem de erro final - o contexto completo da pilha de rastreio é importante. Também é melhor fornecer isto em formato de texto, e não como uma imagem de captura de ecrã.
• Qualquer outra coisa sobre seu computador ou configuração de rede que possa estar a afetar o problema. O seu computador é mais antigo ou mais lento? É uma máquina de trabalho que pode ter firewalls, verificadores de vírus ou outras restrições ativas? A sua rede é especialmente lenta? Executa o sistema operativo com configurações incomuns (como letras muito grandes ou alguma outra tecnologia de assistência ativada)?

Tente pensar fora do comum e inclua tudo o que puder imaginar que possa afetar o problema que está a enfrentar. Se nos der mais do que precisamos, podemos facilmente ignorar o que não precisamos. Não podemos adivinhar algo que deixou de fora.

Um exemplo mínimo

A parte mais importante de um relatório de bug é um caso de reprodução mínimo. Deve ser possível que um terceiro leia as instruções do seu caso de reprodução, siga essas instruções e observe o mesmo problema. Isso pode significar fornecer um projeto de amostra que mostre o problema ou, melhor ainda, usar um exemplo pré-existente (como um tutorial ou um projeto de exemplo que faça parte da base de código existente).

O seu projeto completo não é um caso de reprodução mínima. Um caso de reprodução mínima não deve conter nenhum código que não seja absolutamente necessário para criar o problema. Seja implacável na composição do seu caso de reprodução: se um botão não for necessário para criar o problema, não inclua esse botão.

Muitas vezes, o processo de desenvolvimento desse caso de reprodução mínimo vai revelar a origem do problema, porque o acto de criar o exemplo mínimo o força a descobrir exatamente o que está a causar o problema, seja um bug no código ou decorrente de suposições incorretas ou do uso da API.

Também deve ser explícito em todas as instruções de reprodução. Dizer "Fechar a aplicação de exemplo" pode significar clicar no botão Fechar na janela, selecionar "Sair" num menu ou teclar Control-C num terminal. O seu relatório não deve deixar margem para ambiguidade no que precisa ser feito para reproduzir o problema.

Submeter o relatório

Navegue até lista de problemas do projeto, clique no botão “Novo problema”, e escolha "Relatório de bug” para iniciar o processo.

Tem de preencher todas as secções no modelo de problema. Nós fornecemos o modelo como um aviso para ajuda-lo a fornecer as informações necessárias. Lembre-se de que pode (e deve!) sempre fornecer mais informações daquelas que o modelo exige, mas, no mínimo, precisamos de todas as informações presentes no modelo.

Ao incluir código, caso possa reproduzi-lo com um exemplo existente, como o tutorial do BeeWare, pode fornecer um atalho. Caso contrário, forneça o código no relatório. Ele deve ser formatado em Markdown; um bloco de código precisa de três aspas invertidas (```) antes e depois dele.

Se precisar incluir um bloco longo de texto, pode transforma-lo em conteúdo encolhido usando a seguinte sintaxe:

<details>
<summary>Título do conteúdo encolhido</summary>
Bloco longo de texto.
</details>

Depois de fornecer o máximo de informações possível, clique em "Criar" para submeter o relatório.

Usar a CLI do GitHub para criar um problema

Usar diretamente a CLI do GitHub (gh) passa ao lado dos modelos que criamos. Estes modelos existem para garantir que temos as informações necessárias para se atuar no problema.

Se vai usar gh para criar um novo problema, por favor utilize o seguinte:

gh issue create --web

Usar --web abre um navegador na página do modelo de problema e permite-lhe gerar um problema usando o modelo apropriado.

Propor uma nova funcionalidade

Propor uma nova funcionalidade

Assim se tiver uma ideia sobre uma melhoria para BeeWare - como submete essa ideia para consideração?

Faça a sua pesquisa

A primeira etapa é pesquisar no rastreio de problemas BeeWare os problemas existentes problemas de recursos (problemas com etiqueta "enhancement"), problemas de documentação (problemas marcados como "documentação"), ou Linhas de discussão para ver se a ideia já foi sugerida antes. Se tiver sido, e tiver um novo contexto ou ideias para acrescentar, inclua-os no tópico existente. Se precisar de ajuda com sua pesquisa, pergunte no canal #dev no BeeWare Discord. Talvez possamos indicar os tópicos existentes, fornecer um contexto que talvez não conheça ou ligar a sua ideia a outra ideia que talvez não pareça imediatamente relacionada.

Discutir a ideia

Se não encontrar nenhuma referência existente à sua ideia, inicie uma Linha de discussão. Forneça uma descrição de alto nível da finalidade e do caso de uso de sua ideia. Inclua todas as ideias que tem sobre como o recurso seria, se implementado, como a forma geral de uma API, a aparência visual de uma capacidade ou o documento que seria adicionado. Se for o caso, inclua também qualquer pesquisa que tenha feito sobre como a sua ideia se manifestaria em diferentes plataformas.

Quando o tópico de discussão for aberto, a equipa do BeeWare e o resto da comunidade irão responder. A equipa principal terá como objetivo fornecer pelo menos uma impressão inicial da sua ideia dentro de dois dias úteis. Se uma ideia for especialmente complexa, uma análise mais detalhada poderá levar até uma semana. Eventos como feriados e conferências podem fazer com que esses prazos sejam um pouco mais longos.

Esta é sua oportunidade de participar de uma conversa sobre sua ideia. Podemos solicitar mais detalhes ou contexto. Outros membros da comunidade também poderão envolver-se na discussão, fornecendo outras perspetivas, sugestões ou contrapropostas. O resultado dessa discussão determinará os próximos passos.

É importante entender que nem todas as ideias serão aceitas. O motivo pelo qual esse processo começa com uma proposta é para evitar que você faça todo o trabalho e acabe descobrindo que há um motivo pelo qual a sua alteração não vai ser aceite.

Isto não significa que não seja uma boa ideia! Pode haver motivos técnicos para que ela não possa ser implementada. Por exemplo, podemos rejeitar uma ideia se:

• Seria difícil ou impossível implementar de forma confiável em todas as plataformas suportadas; ou
• Seria difícil de manter, ou a manutenção exigiria acesso a tecnologia ou software que não está amplamente disponível; ou
• Atende a uma ninharia de público, mas impõe uma sobrecarga significativa aos outros utilizadores.

Se determinarmos que a sua ideia não é adequada, isso não significa necessariamente que deva desistir dela. Embora possamos rejeitar uma ideia específica, talvez sejamos muito mais recetivos a adicionar uma interface de plug-in ou outro ponto de extensão que permita manter o mesmo recurso como uma biblioteca externa. Dessa forma, poderá ter o recurso, mas sem que as preocupações específicas de manutenção ou as limitações do recurso se tornem numa restrição ao próprio projeto.

Converter num pedido formal de funcionalidade

Depois que a discussão chegar a um consenso sobre a forma de uma funcionalidade, poderá criar um novo problema de pedido de funcionalidade, no rastreio de problemas BeeWare, que resuma a discussão, com atalhos para a discussão para fins de contexto.

Não precisa implementar a sua proposta de funcionalidade por conta própria; pode abrir um problema com os detalhes do que está a propor. No entanto, o simples facto de publicar a questão não significa que ela será implementada para si. Vai precisar esperar que ela seja potencialmente escolhida por outra pessoa interessada no mesmo recurso, seja outro membro da comunidade ou a equipa principal; no entanto, não há garantia de que isso aconteça. Se quiser a implementação garantida, vai precisar de implementa-la você mesmo ou pagar a alguém para implementa-la por si.

Se estiver interessado, pode começar a implementar a sua nova funcionalidade.