Escreva descrições claras de pull requests com ditado por voz

A alteração está pronta, mas a descrição do pull request ainda diz apenas “atualizar documentação”. Você lembra por que fez a mudança, qual detalhe precisa de uma segunda opinião e o que já verificou. Mesmo assim, colocar esse contexto por escrito parece uma nova tarefa.

O ditado por voz oferece um ponto de partida: explique a alteração como se estivesse conversando com alguém da equipe e depois organize o texto para facilitar a leitura. O guia de revisão do GitHub também destaca a importância do contexto. Veja como transformar sua própria explicação em um rascunho.

1. Fale com a alteração à vista

No Mac, abra os arquivos modificados ao lado de um documento de rascunho ou do formulário do PR. Leia primeiro as diferenças reais. Descreva o que está neste pedido, não tudo o que você pretendia fazer durante o dia.

Comece com uma frase sobre o resultado: “Esta alteração adiciona uma lista de preparação ao guia de contribuição.” Deixe nomes exatos de arquivos, números de issues e comandos para a edição. Copiar esses detalhes costuma ser mais simples do que soletrá-los.

2. Responda a cinco perguntas curtas

Dite em blocos pequenos, fazendo uma pausa entre os pontos:

• O que mudou? Apresente o resultado, não cada ação de edição.
• Por que mudar? Explique o problema ou a informação que estava faltando.
• Por onde começar a revisão? Aponte o trecho que precisa de atenção.
• O que eu verifiquei? Informe as verificações concluídas e seus resultados reais.
• O que ficou em aberto? Separe dúvidas, casos não verificados e trabalho fora do escopo deste PR.

Se o repositório já tem um modelo de descrição, use os títulos existentes. O ditado preenche o rascunho; ele não precisa substituir o formato da equipe.

3. Organize a explicação para quem vai revisar

Este exemplo fictício trata de uma alteração na documentação, não de funcionalidades do TypeFree:

Adicionei uma lista de preparação porque o guia de contribuição pressupunha que o ambiente já estava pronto. Comecem pela seção de pré-requisitos. Abri os links na prévia e eles levam às páginas corretas, mas ainda não segui o processo completo em uma máquina com ambiente limpo. Queria que alguém verificasse se falta algum pré-requisito. Os comandos de instalação não mudaram.

Depois da edição, a descrição poderia ficar assim:

Resumo: Adicionar uma lista de preparação ao guia de contribuição. Os comandos de instalação permanecem iguais.

Motivo: Deixar explícita a preparação necessária para quem vai contribuir pela primeira vez.

Foco da revisão: Verificar se faltam etapas na seção de pré-requisitos.

Verificações concluídas: Abertura de cada link da lista na prévia da documentação; todos levaram ao destino esperado.

Não verificado: Execução do processo completo de configuração em uma máquina com ambiente limpo.

Este é um exemplo de escrita, não um relatório de testes pronto para uso. Substitua cada verificação pelos seus próprios resultados. “Vou testar” é trabalho pendente, não validação concluída.

4. Confira os detalhes que exigem precisão

Copie nomes de arquivos e links da fonte e confirme que pertencem a esta alteração. Preste atenção ao sentido: “comandos alterados” e “comandos não alterados” descrevem escopos opostos.

Retire o relato de cada tentativa, a menos que ele explique uma decisão importante. Quem revisa precisa entender o motivo da solução final, não ler a transcrição da sua tarde inteira. Mantenha as dúvidas visíveis em vez de transformá-las em afirmações definitivas durante a edição.

5. Termine com um pedido específico

Troque “Alguma opinião?” por “Esta lista inclui todos os pré-requisitos necessários para uma primeira contribuição?”. Antes de compartilhar, compare a descrição com os arquivos modificados e os resultados das verificações.

Para tarefas parecidas, veja como escrever relatos de bugs mais claros e criar rascunhos de documentação por voz.

TypeFree é uma forma simples de transformar fala em texto editável e escrever mais rápido. Experimente no próximo PR: explique a mudança em voz alta, acrescente as referências exatas e revise o texto antes de publicar.