Faça mudanças pequenas em uma biblioteca de baixo nível sem quebrar a API pública

## Faça mudanças pequenas e não mexa na API nem na ABI públicas sem pedido Trate uma interface pública estável de programação de aplicações e uma interface binária estável de aplicação como restrições rígidas. ### Antes de Editar - Leia a documentação do repositório sobre compilação, testes, configuração, contribuição e lançamento antes de um trabalho não trivial. - Identifique o único subsistema ou aspecto responsável pela alteração solicitada. - Siga as convenções locais de cada arquivo modificado. - Preserve alterações não relacionadas feitas pelo usuário e artefatos não rastreados. ### Limites da Alteração - Prefira diferenças mínimas e alterações incrementais posteriores a reescritas amplas. - Não renomeie, reordene, reformate nem limpe código não relacionado. - Não adicione uma nova interface pública, a menos que isso tenha sido solicitado explicitamente. - Não altere nem remova uma interface pública ou um contrato binário existente, a menos que isso tenha sido solicitado explicitamente. - Preserve o comportamento de recursos opcionais, as compilações com recursos reduzidos e as proteções condicionais de compilação. - Não altere silenciosamente os padrões de compilação ou de recursos. Quando um código aparentemente estranho estiver em um limite de compatibilidade, suponha que ele possa cobrir um caso extremo real até que testes, histórico e comportamento adjacente demonstrem o contrário. ## Compile pelo fluxo padrão e rode os testes do subsistema alterado Use o fluxo padrão do repositório para configurar, compilar e testar antes de confiar em verificações especializadas. ### Sequência Padrão 1. Configure ou reconfigure o diretório de compilação designado. 2. Compile os alvos afetados. 3. Execute o conjunto de testes adequado à etapa atual. 4. Confirme que a compilação não introduz novos avisos. Se o diretório de compilação não existir, use a configuração inicial em vez de um caminho exclusivo de reconfiguração. Recompile os alvos modificados depois de cada alteração relevante no código. ### Verificações Direcionadas Mínimas - Para lógica de transformação ou composição, execute o conjunto dedicado de testes de comportamento. - Para redução, criação de subconjuntos ou trabalho com grafos, execute o conjunto correspondente do subsistema. - Para trabalho em interfaces públicas, execute o conjunto de testes da interface de programação de aplicações. - Para trabalho em ferramentas de linha de comando, recompile a ferramenta relevante e exercite-a com uma pequena amostra representativa. - Para corrigir um erro ou reforçar um analisador, adicione ou atualize, quando viável, o teste de regressão, a entrada de fuzzing, o alvo de fuzzing ou a saída esperada mais próxima. As verificações direcionadas aceleram a iteração, mas não substituem uma validação mais ampla quando o comportamento compartilhado ou a preparação para lançamento é afetado. ## Escolha onde mudar o código pelo subsistema e siga os padrões do projeto Compreenda as responsabilidades adjacentes antes de escolher onde modificar o código. ### Limites de Responsabilidade - Mantenha o comportamento central da biblioteca separado das ferramentas instaladas, medições de desempenho, documentação, vínculos de linguagem e componentes experimentais. - Trate os auxiliares de grafos como parte do fluxo de redução quando participarem de seu comportamento. - Em unidades de tradução muito grandes de rasterização, vetores, gráficos ou áreas semelhantes, prefira extrair auxiliares específicos e dividir por responsabilidade em vez de acrescentar mais ramificações. - Para uma integração de linguagem, examine tanto a definição nativa de compilação quanto o manifesto do pacote da linguagem antes de alterar a integração de compilação. ### Convenções Existentes - Use os padrões estabelecidos pelo projeto para alocação, erros, previsão de ramificações, objeto nulo, contêineres e utilitários. - Prefira as camadas adaptadoras do projeto às primitivas brutas da plataforma quando elas incorporarem comportamento de portabilidade ou segurança. - Não introduza uma biblioteca externa de contêineres no código central quando o projeto já possuir contêineres e utilitários estabelecidos. - Adicione a documentação da interface pública no local habitual do repositório, seja no código-fonte ou na documentação. Centralize a lógica duplicada de análise, cache ou funções auxiliares quando a duplicação começar a se espalhar, mas não transforme uma correção restrita em uma reescrita arquitetural não relacionada. ## Falhe com segurança diante de erros de memória e entradas hostis em todas as plataformas Trate falhas de alocação, entradas hostis, diversidade de compiladores e compilações com recursos reduzidos como partes normais da superfície suportada. ### Segurança de Alocação e Análise - Siga os padrões existentes de alocação e tratamento de erros para que o novo código falhe com segurança sob pressão de memória. - Examine as proteções existentes do analisador e a infraestrutura de fuzzing antes de reforçar o tratamento de entradas. - Sob uma falha de alocação injetada, o resultado mínimo aceitável é não haver falha abrupta, acesso fora dos limites nem corrupção de memória. - Para componentes experimentais, uma interrupção antecipada com o melhor esforço possível é aceitável sob pressão de memória. - Não adicione uma lógica complexa de reversão apenas para preservar trabalho parcial após uma falha de alocação, a menos que o contrato do componente exija isso. ### Portabilidade - Trate regressões de compilador, sistema operacional, largura de arquitetura, compilação cruzada e compilação com recursos reduzidos como erros reais. - Valide as suposições nos conjuntos de ferramentas e nas larguras de inteiros compatíveis com o projeto. - Mantenha exercitadas as proteções condicionais de compilação e as rotas alternativas. - Ao simplificar código de baixo nível, verifique se a complexidade original tratava alinhamento, estouro, tempo de vida, aliasing ou comportamento específico da plataforma. Prefira uma regressão reproduzível a uma alteração que apenas corrige o problema sem conseguir demonstrar a falha original. ## Regenere as tabelas geradas pelo gerador em vez de editá-las à mão Mantenha todas as descrições de compilação e todas as saídas geradas sincronizadas com a alteração no código-fonte. ### Alterações no Sistema de Compilação - Atualize em conjunto as opções, os resumos de configuração, as ferramentas instaladas, os testes e os alvos dependentes. - Se o empacotamento ou a compilação cruzada forem afetados, examine todos os sistemas de compilação compatíveis em vez de alterar apenas o principal. - Preserve os padrões das opções, a menos que a tarefa exija explicitamente uma alteração de padrão. - Valide tanto as formas habilitadas quanto as desabilitadas dos recursos opcionais afetados. ### Dados Gerados - Modifique o gerador, os dados de origem ou o fluxo de automação da compilação e, em seguida, gere novamente as saídas. - Não edite manualmente tabelas ou índices gerados, a menos que a tarefa exija isso explicitamente. - Não suponha que saídas geradas, recursos locais de teste, fontes tipográficas ou artefatos não rastreados possam ser descartados. - Revise as diferenças regeneradas para detectar abrangência inesperada ou alterações não determinísticas. Se uma alteração no gerador afetar dados públicos ou expectativas de testes, atualize os testes e a documentação relevantes na mesma alteração restrita. ## Adicione API pública só quando pedido, com marcador de versão e documentação Trate o comportamento visível ao usuário como uma alteração coordenada de código, documentação, versionamento e integração de compilação. ### Barreira da Interface Pública - Mantenha as declarações públicas nos cabeçalhos ou módulos públicos designados, não nos arquivos internos de implementação. - Adicione uma nova superfície pública somente quando a solicitação autorizar isso explicitamente. - Quando uma nova interface for autorizada, adicione o marcador de versão e a entrada de notas de lançamento exigidos pelo repositório. - Atualize os índices de seções gerados, os manifestos de documentação ou as listas de referência por meio do fluxo aprovado. - Preserve a disposição binária, a visibilidade dos símbolos, as convenções de chamada e a compatibilidade do código-fonte, a menos que uma alteração incompatível seja explicitamente aprovada. ### Comportamento Visível ao Usuário - Atualize a documentação relevante quando uma funcionalidade se tornar visível por meio de uma biblioteca ou ferramenta instalada. - Mantenha a instalação e a integração de compilação sincronizadas com o comportamento recém-exposto. - Coloque a documentação da interface pública e os índices gerados onde a prática local exigir. - Não desative um teste com falha apenas para obter uma execução bem-sucedida; documente uma exceção justificada e seu impacto. ## Encontre primeiro a causa raiz e faça commit sem fazer push Comprove a causa e o resultado antes de apresentar uma alteração como concluída. ### Método de Trabalho 1. Reproduza o problema quando isso for viável. 2. Compreenda a causa-raiz antes de escrever a correção. 3. Se restar uma ambiguidade relevante, pergunte em vez de adivinhar. 4. Examine o histórico antes de simplificar um código que pareça excepcionalmente complexo. 5. Adicione ou atualize a cobertura de regressão mais próxima. 6. Valide o subsistema alterado, as configurações afetadas e o comportamento mais amplo. ### Disciplina de Commit - Execute o conjunto completo de testes antes de fazer commit de código, lógica de compilação, saídas geradas ou entradas de teste. - Alterações exclusivas de documentação ou de integração contínua podem omitir os testes completos somente quando não puderem afetar essas áreas; informe a omissão. - Mantenha cada commit concentrado em um único problema ou aspecto. - Nunca envie alterações ao repositório remoto; deixe o envio para a pessoa autorizada. - Use o prefixo de subsistema, os rodapés de atribuição e as convenções de mensagem do repositório. - Para uma mensagem de commit com várias linhas, use um arquivo ou uma entrada apoiada por editor em vez de sequências de nova linha com escape. - Descreva a causa-raiz, a correção e os testes somente quando isso for sustentado pelo trabalho realmente realizado. Na entrega, informe o escopo alterado, os testes executados, os avisos, as configurações não compatíveis, os riscos não resolvidos e qualquer validação não realizada.