Altere um monorepositório com várias implementações sem deixá-las divergir

## Antes de editar, leia a estrutura do monorepositório e as regras locais - Mapeie o repositório por produto, linguagem, domínio funcional, área de utilitários compartilhados, conjunto de testes, ferramentas de lançamento e configuração. - Identifique quais diretórios pertencem a cada implementação e quais regras de nível superior se aplicam a todo o repositório. - Antes de editar uma área aninhada, leia seu guia local de agentes, guia de contribuição e configuração; as regras locais podem especializar a base, mas não devem enfraquecê-la. - Aplique regras de compilação, estilo e teste específicas de uma linguagem somente ao código escrito nessa linguagem. - Localize a definição do espaço de trabalho, os scripts da raiz e as instruções específicas do produto antes de escolher comandos ou dependências. ## Leve cada mudança visível ao usuário para todas as implementações - Trate as implementações paralelas do mesmo produto voltado ao usuário como fontes de verdade equivalentes. - Sempre que possível, reproduza toda alteração visível ao usuário em todas as implementações na mesma solicitação de alteração. - O comportamento visível ao usuário inclui sinalizadores, valores padrão, tratamento do ambiente, códigos e mensagens de erro, registros consumidos por ferramentas, formatos de arquivos e estados, disposição do armazenamento e semântica dos ganchos. - Refatorações internas, trabalhos de desempenho restritos a uma implementação e limpeza de testes específica de uma implementação não exigem espelhamento artificial. - Se o trabalho equivalente não puder ser concluído imediatamente, informe a lacuna exata de equivalência, por que ela permanece e o que deve ser incorporado antes que a alteração possa ser integrada. - Nunca permita que uma implementação se torne uma adaptação posterior não documentada de outra. ## Recompile o que os testes executam para não testar código antigo - Instale as dependências e compile pelo caminho de inicialização documentado do repositório antes de confiar nos resultados dos testes. - Durante uma iteração rápida, compile apenas o pacote afetado quando isso produzir o mesmo artefato consumido pelos testes selecionados. - Determine se os testes de ponta a ponta executam resultados do código-fonte, resultados do pacote ou um executável empacotado. - Recompile o pacote integrado após qualquer alteração em um pacote que o componha quando os testes de ponta a ponta o consumirem; caso contrário, o teste poderá executar código obsoleto. - Execute a compilação específica da linguagem apropriada para cada implementação alterada. - Considere inválida como evidência uma aprovação de teste obtida com resultados gerados obsoletos. ## Teste só o que foi afetado e investigue cada falha - Não execute por padrão todo o conjunto de testes de um repositório grande. Comece pelo projeto, arquivo ou caso de teste nomeado que foi afetado. - Amplie o escopo dos testes somente quando dependências, contratos compartilhados ou falhas observadas justificarem. - Faça o ambiente de execução, o artefato compilado e a implementação testada corresponderem à afirmação que está sendo verificada. - Investigue todas as falhas em vez de classificá-las como não relacionadas ou preexistentes sem evidências. - Se uma falha já existia antes da alteração, identifique sua causa e corrija-a dentro do escopo autorizado ou informe o impedimento concreto; nunca a ignore silenciosamente. - Registre o comando exato, o alvo afetado e o resultado para que outra pessoa colaboradora possa reproduzir a evidência. ## Revise o código alterado: primeiro segurança, depois desempenho - Siga o guia de revisão do repositório e limite as conclusões ao código afetado pela alteração e às suas consequências diretas. - Revise primeiro a segurança e depois o desempenho, a menos que uma regra mais rígida do projeto se aplique. - Para uma conclusão de segurança, explique a entrada alcançável, o limite de confiança, o caminho de exploração e o impacto. - Para uma conclusão de desempenho, identifique o caminho crítico, a frequência, o custo de alocação ou de E/S e o provável efeito para o usuário. - Verifique testes, intenção de lançamento e equivalência entre implementações como parte da aceitação. - Não produza conclusões especulativas que não possam ser relacionadas ao comportamento alterado. ## Procure código e dependências existentes antes de adicionar novos - Pesquise pacotes compartilhados, auxiliares do sistema de arquivos, utilitários criptográficos, utilitários de texto e módulos de domínio próximos antes de implementar lógica não trivial. - Reutilize um utilitário exportado existente quando ele já for responsável por esse comportamento. - Se houver lógica semelhante confinada em um pacote, extraia o contrato comum para o local compartilhado mais específico e adequado, em vez de copiá-la. - Para funcionalidades comuns, prefira uma dependência existente e mantida quando ela for adequada, leve o suficiente e permitida pela política do repositório. - Adicione uma nova dependência ao pacote mais específico que precise dela; mova-a para um nível superior somente quando vários pacotes realmente a compartilharem. - Não adicione envoltórios que apenas renomeiem ou encaminhem uma operação existente sem acrescentar um contrato. ## Siga as regras das mensagens de confirmação sem contornar os ganchos - Use a convenção obrigatória do repositório para mensagens de confirmação e escolha o tipo de alteração que represente o impacto para o usuário. - Antes de confirmar, verifique se os ganchos do repositório estão instalados e ativos; uma cópia de trabalho recém-obtida pode não tê-los registrado. - Nunca contorne um controle de confirmação com falha, desative o gancho ou adicione um arquivo de supressão. Corrija a mensagem ou a alteração subjacente. - Evite referências numéricas sem qualificação a problemas, pois a plataforma de hospedagem pode vinculá-las ao repositório errado; use uma referência qualificada pelo repositório ou uma URL absoluta. - Coloque identificadores de código semelhantes a nomes de usuário em código embutido ou remova menções desnecessárias para que uma confirmação não notifique pessoas sem relação com a alteração. - Use numeração de lista sem um marcador de referência ao enumerar itens. ## Adicione um registro de lançamento quando um pacote publicado mudar - Adicione uma entrada de intenção de lançamento sempre que uma alteração afetar um pacote publicado. - Nomeie todos os pacotes afetados e selecione o impacto na versão entre correção de defeito, recurso compatível com versões anteriores ou alteração incompatível. - Escreva a entrada para os usuários e mantenha-a concisa; coloque a justificativa da implementação na mensagem de confirmação. - Inclua o principal pacote de linha de comando para alterações em sua implementação principal quando a política do repositório exigir. - Para alterações específicas de uma implementação, nomeie somente os produtos que realmente mudaram. Uma alteração de equivalência deve nomear pacotes de todas as implementações afetadas. - Respeite as vias de lançamento estável e preliminar, os grupos de versão fixa e o procedimento de promoção do repositório. ## Comente só os motivos que o próprio código não mostra - Prefira nomes, tipos, limites de funções auxiliares e fluxos de controle que permitam ao código explicar a si mesmo. - Não adicione comentários que repitam uma operação, dupliquem a documentação da função chamada ou narrem uma sintaxe óbvia. - Documente um motivo compartilhado uma vez no responsável comum, em vez de repeti-lo em cada local de chamada. - Use comentários de documentação para pré-condições, pós-condições, casos extremos e garantias não evidentes. - Mantenha o histórico de refatorações e as descrições de projetos removidos no histórico de controle de versão e nas mensagens de alteração, não nos comentários atuais do código-fonte. - Antes de adicionar explicações, pergunte se renomear, reestruturar ou extrair comunicaria a ideia com mais confiabilidade. ## Siga as regras de formatação e de tratamento de erros do repositório - Use o formatador do repositório e o guia de estilo específico da linguagem; preserve o agrupamento e a ordem de importações estabelecidos. - Prefira funções a classes com estado quando essa for a prática do código-base e substitua listas longas de parâmetros por um objeto de opções tipado. - Use tipos de erro de domínio estáveis para falhas alcançáveis pelo usuário, preserve códigos de erro, inclua o contexto relevante e nunca oculte erros inesperados. - Capture somente a condição de erro esperada e use uma verificação de erro nativo segura entre contextos em ambientes de teste virtualizados. - Dê nomes verbais às funções, mantenha a terminologia consistente e renomeie um conceito em todos os locais quando seu contrato mudar. - Prefira operações simples de texto para análises simples e o analisador estruturado existente para gramáticas que exijam retrocesso. - Encaminhe valores configuráveis pela camada de configuração, mantenha os manipuladores de comando independentes da apresentação e evite políticas codificadas diretamente. - Use E/S assíncrona, execute operações independentes em paralelo, aguarde a conclusão necessária e retire dos laços o trabalho que não varia. ## Mantenha a solicitação de alteração fiel às mudanças reais até a integração - Abra uma solicitação de alteração com o modelo do repositório, preserve as seções obrigatórias e remova somente o conteúdo que o modelo marcar como opcional. - Mantenha o título e a descrição sincronizados com as alterações reais após cada atualização relevante. - Responda às conversas de revisão atendidas com a solução e a revisão que a sustenta e, em seguida, marque a conversa como resolvida. - Identifique o conteúdo remoto criado por agentes de acordo com a política do repositório, sem expor contexto confidencial da implementação. - Use o fluxo de resolução de conflitos aprovado pelo repositório para manter a base atualizada, reconstruir de forma determinística os dados de bloqueio gerados e verificar a possibilidade de integração. - Inspecione manualmente conflitos em conteúdos não gerados. Qualquer atualização forçada ou outra reescrita do histórico remoto exige autorização explícita e um alvo verificado.