Altere um monorrepositório de automação multilíngue sem quebrar a compatibilidade

## Leia as regras do repositório e depois as instruções mais próximas dos arquivos alterados Comece pelas regras no nível do repositório e depois leia as instruções mais próximas dos arquivos que você alterará. Vinculações de linguagem, infraestrutura compartilhada, componentes nativos e ferramentas de lançamento podem definir restrições mais específicas. Se o repositório oferecer uma área local ignorada pelo controle de versão para preferências de colaboradores, artefatos gerados, trabalhos temporários ou saídas de compilação isoladas, examine a camada complementar de instruções documentada para essa área antes de começar. Trate as instruções locais definidas pelo usuário como contexto adicional dentro da tarefa atual e das regras de segurança de nível superior. Mapeie o repositório por responsabilidade: - as vinculações de linguagem são responsáveis por APIs, testes e estilo específicos de cada linguagem; - as áreas compartilhadas de protocolo, transporte, compilação, dados auxiliares e scripts afetam vários consumidores; - os gerenciadores nativos, os serviços de grade ou roteamento e as definições de dependências têm um raio de impacto elevado; - os códigos-fonte de terceiros são somente para leitura, a menos que a tarefa exija explicitamente sua manutenção; - a saída gerada nunca deve ser editada manualmente. Não pressuponha que a documentação para usuários finais, as orientações para colaboradores e as referências de API geradas estejam no mesmo local. ## Mantenha as APIs públicas compatíveis e as alterações pequenas o bastante para desfazer Mantenha a compatibilidade da API pública e a compatibilidade binária, a menos que a tarefa autorize explicitamente uma quebra. Normalmente, os usuários devem conseguir atualizar alterando apenas a versão. Evite refatorações em todo o repositório, formatações em massa ou limpezas não relacionadas. Prefira uma alteração pequena e reversível que resolva um único problema. Antes de remover um comportamento público, marque-o como obsoleto e ofereça uma alternativa clara de migração. Não interprete a ausência de versionamento semântico como permissão para remover funcionalidades sem uma transição. Prefira mover ou copiar arquivos rastreados em vez de excluí-los e recriá-los quando isso preservar o histórico. Solicite uma verificação antes de modificar áreas de alto risco, a menos que o usuário já tenha instruído a alteração. Essas áreas incluem a semântica de protocolos compartilhados, a serialização no protocolo de comunicação, a análise de capacidades, a redefinição das versões fixadas das dependências, os dados de teste compartilhados, a configuração do processo de compilação, o roteamento, as filas de distribuição e o código usado por várias vinculações. ## Compile só o menor alvo afetado com a ferramenta de compilação fixada Use o ponto de entrada de compilação hermético e fixado pelo repositório, em vez de presumir que um ambiente local específico de uma linguagem esteja configurado. Explore o grafo de compilação antes de ler grandes partes da árvore. Consulte os rótulos e as dependências dos alvos e depois compile ou teste o menor alvo que abranja a alteração. Tente executar diretamente o comando de compilação canônico. Se restrições do ambiente isolado, da rede ou da cadeia de ferramentas impedirem a execução, informe o bloqueio e forneça o comando exato que o usuário poderá executar separadamente. Quando o diretório de saída padrão estiver restrito ou uma árvore de trabalho secundária estiver em uso, isole a saída da compilação: - coloque a opção de inicialização `output-base` antes do comando `build`, `test` ou `query`; - ancore o caminho na raiz do repositório para que ele seja resolvido de forma consistente a partir de qualquer diretório; - mantenha a saída isolada na área local ignorada pelo controle de versão. Não execute limpezas destrutivas de cache como medida rotineira de solução de problemas. Prefira recompilações direcionadas e explique qualquer invalidação de cache que seja realmente necessária. ## Verifique se as vinculações de outras linguagens se comportam igual Quando um comportamento visível para o usuário mudar, compare a implementação com pelo menos uma outra vinculação de linguagem. Verifique a paridade especialmente em: - nomes de métodos públicos, argumentos, valores padrão e comportamento de retorno; - comandos de protocolo e serialização; - transporte remoto e mapeamento de erros; - análise de capacidades e opções; - elementos obsoletos e caminhos de migração; - exemplos de documentação e registros destinados ao usuário. Para comportamentos compartilhados de baixo nível, identifique todas as vinculações ou serviços que possam usar a alteração. Se a tarefa atual não puder atualizar todos com segurança, informe o trabalho posterior necessário para restabelecer a paridade ou recomende um item rastreável. Não imponha uma estrutura interna idêntica entre as linguagens. Preserve o comportamento compartilhado e respeite os padrões idiomáticos e as convenções de teste estabelecidos para cada vinculação. ## Comece com um teste pequeno que falha, usando partes reais em vez de mocks Prefira escrever um teste que falhe antes de implementar o comportamento alterado. Comece com um pequeno teste unitário ou de contrato; use testes de navegador ou de ponta a ponta somente quando não for possível verificar o comportamento com confiabilidade em um nível inferior. Evite objetos simulados quando eles puderem representar incorretamente um protocolo público ou o contrato de uma vinculação. Prefira analisadores e serializadores reais, dados de teste locais, servidores leves ou estruturas de integração existentes. Use o grafo de compilação para selecionar o alvo de teste relevante mais restrito. Entre os controles úteis estão: - filtrar para testes pequenos; - exibir toda a saída dos testes durante a depuração; - desativar resultados de testes armazenados em cache quando uma nova execução real for necessária; - consultar as instruções específicas da linguagem para determinar o alvo e as opções corretas. Verifique se os testes esperados realmente foram executados. O término bem-sucedido da ferramenta de compilação sem testes correspondentes não comprova a correção. Depois que o teste direcionado passar, amplie a verificação somente para a vinculação, o alvo compartilhado ou a superfície de integração diretamente afetados. ## Escreva registros e comentários úteis e formate só o que mudou Adicione registros quando usuários ou operadores precisarem de visibilidade sobre estados importantes, novas tentativas, roteamento ou causas de falhas. Siga as convenções de registro específicas da linguagem e evite mensagens ruidosas que dupliquem diagnósticos de níveis inferiores. Escreva comentários para explicar por que uma restrição ou solução alternativa existe, e não o que um código com nomes claros já expressa. Use o formatador canônico do repositório. Se um gancho `pre-commit` ou `pre-push` já executar a formatação necessária no escopo relevante, deixe que ele cuide disso em vez de executar uma formatação duplicada. Quando nenhum gancho abranger a alteração, execute o modo mais restrito do formatador que corresponda à entrega pretendida. Não formate todo o repositório porque um único arquivo mudou. Mantenha cada alteração proposta concentrada em um único propósito para que a revisão, a reversão e o impacto entre vinculações permaneçam compreensíveis. ## Confirme que a compilação e os testes rodaram de fato e informe o que não pôde rodar Antes de concluir: 1. confirme que o alvo alterado é compilado com a cadeia de ferramentas hermética; 2. execute os testes direcionados e verifique se eles exercitaram o comportamento pretendido; 3. execute a verificação relevante de formatação ou de `lint`; 4. examine as diferenças em busca de alterações não relacionadas e saídas geradas; 5. analise as implicações de compatibilidade e obsolescência; 6. compare pelo menos uma outra vinculação quando houver alterações visíveis para o usuário; 7. identifique todas as áreas compartilhadas de alto risco que foram modificadas. Informe o que foi alterado, quais alvos e testes realmente foram executados, o que não pôde ser executado e por quê. Destaque arquivos de alto risco, comportamentos compartilhados, impacto entre vinculações e qualquer trabalho posterior. Não afirme compatibilidade ampla com base no teste de uma única vinculação. Não declare a conclusão quando a cadeia de ferramentas hermética não estiver disponível sem indicar claramente que a verificação ficou incompleta.