Enviando 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. Veja a seguir como enviar um bom relatório de bug para BeeWare.

Pesquisar problemas existentes

Antes de enviar um novo problema, pesquise no índice os 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 você estiver vendo o problema em uma versão diferente do Python ou em um sistema operacional diferente, essas informações adicionais podem ser úteis para determinar o impacto ou a causa de um problema.

Se você encontrar um problema encerrado que pareça 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 será corrigido na próxima versão. Se o problema foi encerrado há mais de 4 meses, é provável que o que você esteja enfrentando seja um problema diferente, por mais semelhante que seja a mensagem de erro.

Se você não encontrar um problema que corresponda ao que está vendo, talvez seja apropriado abrir um novo problema.

Comece com uma discussão

Antes de enviar um problema para o GitHub, considere começar com uma discussão para perguntar se o que está acontecendo é realmente um bug ou um problema com sua configuração ou processo. A menos que esteja vendo 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 você tiver encontrado um problema, um tópico de discussão pode ser facilmente transformado em um problema.

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

Como 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 você puder fornecer. Isso inclui, mas definitivamente não se limita a:

• A versão do seu sistema operacional - até a versão micro (por exemplo, macOS 15.7.2).
• Sua versão do Python, também até a versão micro (por exemplo, 3.14.1).
• Como você instalou o Python. Você o baixou do python.org? Você usou o Homebrew? uv? pyenv? conda? Alguma outra coisa?
• A versão específica das ferramentas BeeWare que você está usando (por exemplo, Toga 0.5.3). Se estiver usando uma versão de desenvolvimento, qual hash do Git você está usando? Não basta dizer "o ramo principal atual", pois isso pode mudar diariamente.
• As versões específicas de outros pacotes que devem ser instaladas para acionar o problema. Você pode incluir os resultados da execução de python -m pip freeze para fornecer essas informações.
• Se um arquivo de registro tiver sido gerado, o arquivo de registro inteiro.
• Se um rastreamento de pilha tiver sido gerado, o rastreamento de pilha inteiro. Não forneça apenas a mensagem de erro final - o contexto completo do rastreamento de pilha é importante. Também é melhor fornecer isso em formato de texto, não como uma captura de tela.
• Qualquer outra coisa sobre seu computador ou configuração de rede que possa estar afetando o problema. Seu computador é mais antigo ou mais lento? É uma máquina de trabalho que pode ter firewalls, verificadores de vírus ou outras restrições em vigor? Sua rede é especialmente lenta? Você executa o sistema operacional com padrões incomuns (como uma fonte muito grande ou alguma outra tecnologia de assistência ativada)?

Tente pensar fora da caixa e inclua tudo o que puder imaginar que possa afetar o problema que está enfrentando. Se você nos der mais do que precisamos, podemos facilmente ignorar o que não precisamos. Não podemos pensar em algo que você 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 de seu caso de reprodução, siga essas instruções e observe o mesmo problema. Isso pode significar fornecer um projeto de amostra que exiba 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).

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

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

Você também deve ser explícito em todas as instruções de reprodução. Dizer "Fechar o aplicativo de exemplo" pode significar clicar no botão Fechar na janela, selecionar "Sair" em um menu ou digitar Control-C em um terminal. Seu relatório não deve deixar margem para ambiguidade no que precisa ser feito para reproduzir o problema.

Envio do relatório

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

Você deve preencher todas as seções no modelo de problema. Fornecemos o modelo como um prompt para ajudá-lo a fornecer as informações necessárias. Lembre-se de que você pode (e deve!) sempre fornecer mais informações do que o modelo exige, mas, no mínimo, precisamos de todas as informações presentes no modelo.

Ao incluir o código, caso possa reproduzi-lo com um exemplo existente, como o tutorial do BeeWare, você pode fornecer um link. 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 pontos finais (```) antes e depois dele.

Se precisar incluir um bloco longo de texto, você pode transformá-lo em conteúdo recolhido usando a seguinte sintaxe:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

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