Alterar código em um repositório grande com várias linguagens compilando e testando só o necessário

## Pesquisar e planejar, depois fazer e testar a menor mudança Use uma sequência repetível em cada alteração: 1. Pesquise a solicitação, o código relevante, as interfaces das dependências, os testes existentes e os modos de falha conhecidos. 2. Elabore um plano de implementação de alto nível e examine criticamente suas premissas, casos extremos e riscos operacionais. 3. Inspecione código semelhante para conhecer a organização, a nomenclatura, o tratamento de erros e os padrões de teste do repositório. 4. Apresente o plano somente quando o usuário solicitar; caso contrário, prossiga com a implementação. 5. Implemente a menor alteração coerente que atenda à solicitação. 6. Revise o resultado quanto à correção das APIs, clareza, desempenho, legibilidade e ampliação involuntária do escopo. 7. Execute a formatação, compilações direcionadas e testes relevantes; depois, repita o ciclo para corrigir falhas. Não considere a elaboração do rascunho como conclusão. Uma alteração só estará pronta depois que a implementação e o comportamento diretamente afetado forem revisados e validados. ## Antes de editar, seguir o padrão do código parecido mais próximo Leia as diretrizes de contribuição do repositório e todas as instruções específicas de caminho que regem os arquivos que serão alterados. Encontre o equivalente funcional mais próximo, como uma classe irmã, um pacote adjacente, um teste semelhante ou um fluxo de trabalho relacionado, e siga sua estrutura estabelecida, a menos que a tarefa exija um desvio intencional. Verifique as APIs das dependências e os casos extremos por meio de interfaces oficiais ou usos existentes. Localize os testes atuais antes de criar novos e integre a nova cobertura aos frameworks existentes do repositório, em vez de inventar uma infraestrutura paralela. Mantenha a investigação concentrada no comportamento solicitado. Não combine a alteração com renomeações, movimentações de diretórios, mudanças extensas apenas de formatação ou reorganizações arquitetônicas sem relação com a tarefa. ## Antes de testar, verificar as ferramentas e o hardware disponíveis Antes de escolher comandos, determine quais compiladores, ambientes de execução, ferramentas de compilação, contêineres, aceleradores e credenciais estão realmente disponíveis. Diferencie uma capacidade indisponível de uma falha do produto: a ausência de um dispositivo, um runtime de contêiner não compatível ou uma cadeia de ferramentas inexistente não prova que o código apresenta defeito. Use o contêiner ou ambiente de desenvolvimento padrão do repositório quando houver compatibilidade e ele for necessário para a reprodutibilidade. Caso contrário, execute todas as verificações significativas disponíveis no ambiente atual e identifique o menor comando restante que exija outra máquina ou uma ação do usuário. Nunca afirme que um teste indisponível foi aprovado. Relate a limitação exata, a validação concluída sem ele e o risco residual. ## Compilar e testar só as partes afetadas pela mudança Prefira as predefinições e os scripts auxiliares fornecidos pelo repositório a sequências de comandos criadas manualmente. Descubra as predefinições compatíveis, selecione aquela que corresponde ao componente alterado e ao nível da linguagem e direcione apenas os alvos de compilação, testes unitários, testes de integração ou verificações do compilador relevantes. Use informações de dependência para incluir componentes posteriores afetados por uma alteração compartilhada ou de alta dependência. Em uma alteração local, evite recompilar pacotes sem relação com ela. Reserve compilações e conjuntos de testes completos para alterações transversais, bloqueios de lançamento ou políticas do repositório que os exijam explicitamente. Registre por que o escopo escolhido é suficiente. Uma verificação restrita só tem valor quando sua relação com a alteração está clara. ## Testar cada linguagem e arquitetura de hardware do seu próprio jeito Trate cada linguagem ou camada de pacotes de acordo com sua própria interface. Bibliotecas nativas podem exigir configurações de compilador, padrão da linguagem e arquitetura, enquanto pacotes de linguagens de script podem exigir versões do ambiente de execução, dependências adicionais e pontos de entrada de teste específicos do pacote. Não passe os parâmetros de um ecossistema para outro. Para código sensível à arquitetura, diferencie verificações executadas somente no host, verificações apenas de compilação, simuladores ou alvos virtuais e testes que exigem hardware físico. Selecione arquiteturas representativas com base no comportamento alterado e no intervalo de compatibilidade aceito, em vez de compilar todas as variantes por padrão. Quando um componente compartilhado for alterado, inspecione o grafo de dependências e valide os consumidores com maior probabilidade de revelar regressões de compatibilidade. ## Fazer primeiro as verificações baratas e não interromper builds lentos cedo demais Presuma que compilações grandes, matrizes de testes geradas e conjuntos de testes apoiados por hardware podem levar bastante tempo. Defina limites de tempo realistas, use caches compatíveis, limite as arquiteturas e os alvos durante a iteração e amplie a cobertura somente quando o risco ou a etapa de lançamento justificar o custo. Uma longa duração, por si só, não comprova um travamento. Não cancele uma compilação ou um teste em andamento apenas porque está lento; interrompa somente quando houver evidência concreta de falha, um limite operacional explícito ou uma instrução do usuário. Organize a validação em etapas para receber primeiro o retorno de menor custo: formatação e verificações estáticas, compilação direcionada, testes executáveis no host e, por fim, conjuntos especializados ou dependentes de hardware. Preserve a cobertura final exigida mesmo quando as primeiras iterações usarem um subconjunto menor. ## Reduzir a CI durante a iteração, mas rodá-la completa antes da mesclagem Use a detecção de alterações e matrizes de tarefas para executar os trabalhos relevantes aos componentes afetados. Matrizes de sobrescrita temporária ou controles de omissão podem reduzir o custo durante as primeiras iterações, especialmente em alterações de infraestrutura ou áreas com muitas dependências, mas devem permanecer visíveis e auditáveis. Trate a cobertura reduzida da CI como um bloqueio da mesclagem. Antes de mesclar, restaure a configuração completa exigida pelo repositório e obtenha uma execução bem-sucedida sem sobrescritas temporárias nem controles de omissão. Não remova a sobrescrita de outro colaborador nem altere seu escopo sem orientação explícita. Mantenha a configuração de sobrescrita estruturalmente válida quando o fluxo de trabalho esperar um valor vazio em vez da remoção. Confirme que a agregação de resultados encerra com falha de forma segura quando trabalhos obrigatórios falharem ou a cobertura reduzida permanecer ativa. ## Rodar formatador e linter e relatar as verificações não executadas Antes de confirmar as alterações, execute o formatador, o linter e as verificações de pre-commit do repositório nos arquivos modificados. Aplique primeiro as diretrizes de estilo comuns e, em seguida, as regras específicas da linguagem, do diretório ou dos testes determinadas pelos caminhos afetados. Revise a diferença final para detectar arquivos acidentais, artefatos gerados, nomenclatura inconsistente, comentários desatualizados e testes ausentes. Execute novamente a validação direcionada depois da edição final para que as evidências relatadas correspondam ao conteúdo entregue. Relate as verificações exatas executadas, seus resultados, as verificações não realizadas, o motivo de sua indisponibilidade e o risco residual resultante. Nunca descreva uma alteração como totalmente validada quando o hardware, as ferramentas, as permissões ou a cobertura de CI exigidos estiverem ausentes.