Faça mudanças testadas e prontas para revisão em uma base de código grande

## Compile e rode os testes só pelo wrapper do projeto Projetos grandes geralmente encapsulam o compilador e o executor de testes em um único comando do projeto, que recompila e injeta suas mudanças locais antes de rodar qualquer coisa. Sempre compile e execute por meio desse wrapper. Nunca chame o executor de testes bruto ou um binário compilado anteriormente de forma direta, porque isso executa artefatos desatualizados que não incluem sua mudança, então um resultado bem-sucedido não prova nada. Aprenda quais edições podem pular a recompilação nativa. Mudanças que afetam apenas entradas não compiladas, como declarações de tipo ou scripts empacotados que recarregam sozinhos, não precisam de uma compilação completa, e forçar uma só desperdiça tempo; nesses casos, rode diretamente a verificação direcionada mais leve. Não coloque um limite de tempo em uma compilação completa. Uma compilação a frio legítima pode demorar bastante, e interrompê-la produz falhas confusas e enganosas. Quando o wrapper repassa argumentos finais ao programa compilado, coloque as flags de compilação antes desses argumentos de execução para que o roteamento permaneça inequívoco. ## Adicione testes ao arquivo de testes existente do código que você muda Por padrão, adicione seu teste ao arquivo de teste existente para o código que você está alterando. Um bug no comportamento de uma área pertence ao arquivo de teste já existente daquela área, não a um arquivo totalmente novo. Manter um teste junto à cobertura relacionada é o que o torna descobrível e evita configurações duplicadas. Reflita a estrutura de testes já estabelecida no repositório: testes unitários agrupados por subsistema, testes de compatibilidade, testes de plataforma e de APIs web, testes de linha de comando e testes de integração ponta a ponta, cada um em sua própria área. Coloque seu teste onde já existe cobertura equivalente. Reserve pastas de propósito especial exatamente para o caso a que se destinam. Uma pasta de regressão identificada por um número de issue serve apenas para uma regressão verdadeira, ou seja, um comportamento que funcionava em uma versão anterior e depois quebrou, e esse identificador precisa ser real, nunca um valor provisório. Se o comportamento nunca esteve correto, não se trata de uma regressão, e o teste pertence ao arquivo comum daquele módulo. ## Escreva testes que deem o mesmo resultado a cada execução Prefira asserções de snapshot a verificações de igualdade frágeis em saídas grandes, e normalize o snapshot para que valores incidentais, como caminhos temporários, não causem alterações desnecessárias. Nunca escreva um teste que apenas verifica a ausência de uma falha ou de uma string de exceção não tratada; esse tipo de teste nunca falha no pipeline e dá uma falsa sensação de segurança. Elimine toda fonte de não determinismo. Não fixe uma porta de rede no código; vincule-se a uma porta efêmera e leia de volta a que foi atribuída. Nunca use "sleep" ou um temporizador para esperar por algo, porque você está testando a condição, não a passagem do tempo; aguarde a condição real. Use o auxiliar de diretório temporário do próprio framework de testes em vez de criar diretórios temporários manualmente, e evite utilitários de shell, como busca de arquivos ou de texto, dentro de um teste, usando as APIs de arquivo do próprio projeto. Quando um teste inicia um processo, verifique a saída dele antes de verificar o código de saída, para que uma falha gere uma mensagem útil em vez de apenas um status diferente de zero. ## Confirme que os testes novos falham sem a mudança e relate só o que executou Uma mudança não está concluída até que seja testada. Se você não rodou os testes, considere que o código não funciona; rodá-los faz parte de terminar o trabalho, não é um acompanhamento opcional. Comprove que cada novo teste realmente exercita sua mudança. Ele deve falhar contra a base não modificada e passar contra a sua compilação. Um teste que já passa mesmo sem sua mudança não prova nada, então confirme as duas direções antes de confiar nele. Seja humilde e honesto em cada mensagem de commit, resposta de revisão e atualização de status. Nunca exagere o que você realizou ou o que realmente funciona. Relate apenas os resultados que você observou na sua própria execução, e deixe claro o que ainda está sem verificação ou incompleto, em vez de dar a entender que o trabalho está pronto. ## Entenda como a base de código é organizada antes de editá-la Antes de editar, entenda como a base de código está organizada: qual camada é responsável por qual funcionalidade, onde ficam os utilitários compartilhados e quais arquivos são gerados versus escritos manualmente. Arquivos gerados são produzidos a partir de definições de origem, então edite a origem e deixe a compilação regenerá-los; nunca edite manualmente uma saída gerada, porque a próxima compilação irá sobrescrevê-la. Identifique o subsistema responsável pelo comportamento que você está mexendo, seja ele o parsing, a resolução de módulos, as APIs de runtime, a rede, o armazenamento, o bundler ou o gerenciador de pacotes, de modo que tanto a sua mudança quanto o teste dela fiquem no lugar certo. Siga o estilo de código já existente. Verifique os arquivos vizinhos em busca dos padrões estabelecidos e siga-os, em vez de importar convenções de outro projeto. Prefira o idioma nativo da linguagem para gerenciamento de recursos, como a limpeza automática baseada em escopo, em vez de uma finalização manual, e respeite os casos extremos documentados, por exemplo, valores alocados em uma região que pula seus destrutores ao reiniciar e que precisam ser liberados explicitamente antes. ## Leia as regras de revisão e siga as convenções obrigatórias do projeto Um projeto maduro condensa aquilo pelo qual seus revisores bloqueiam merges em um conjunto de regras escritas. Leia-o antes de escrever código que faça uma escolha não óbvia, e leia qualquer guia específico para a área que você está mexendo, como camadas de compatibilidade, design de API voltada ao usuário, caminhos críticos sensíveis a desempenho, código restrito por plataforma, mudanças de dependências e vendoring, ou documentação e declarações de tipo, antes de fazer esse trabalho específico. Siga exatamente as convenções obrigatórias do projeto, porque o pipeline automatizado as impõe. Use o prefixo de nome de branch exigido, mantenha os comentários no código curtos, deixando explicações mais profundas para a documentação e escrevendo-as apenas quando explicitamente solicitado, e use caminhos absolutos em operações com arquivos. Ao fazer uma mudança específica de plataforma, compile para todos os alvos suportados, já que código compilado condicionalmente não é verificado quanto a tipos, a menos que o alvo correspondente seja realmente compilado. ## Use as ferramentas de diagnóstico do projeto quando a compilação falhar, e corrija-as se mostrarem dados errados Quando uma compilação automatizada falha, use os comandos de diagnóstico dedicados do projeto, aqueles que exibem os testes que falharam, resumem o status dos jobs e salvam os logs completos, em vez de reconstruir esse quadro manualmente. Eles já separam falhas novas daquelas que também falham em outros lugares e filtram o ruído rotineiro. Ao ler o feedback sobre uma mudança, use o comando que retorna o quadro completo. Uma listagem geral costuma omitir silenciosamente resumos de revisão e comentários em nível de linha, então prefira a ferramenta que retorna comentários de nível superior, revisões e comentários inline juntos, em uma única visão cronológica e rotulada. Se a saída de um auxiliar parecer errada, como uma anotação interpretada incorretamente ou um campo cujo formato de origem mudou, corrija o próprio apresentador em vez de contorná-lo mais adiante. O auxiliar é uma camada fina sobre a ferramenta subjacente, e consertá-lo mantém correta toda execução posterior.