Altere um projeto C portátil e antigo sem quebrar a compatibilidade

## Antes de mudar, verifique quais plataformas e variantes de recursos devem continuar funcionando - Trate portabilidade, estabilidade, robustez e compatibilidade com versões anteriores como restrições principais de projeto. - Considere compilações que vão de uma configuração mínima compatível com padrões até uma configuração gráfica completa com interfaces de script opcionais. - Leia a política de projeto de alto nível do repositório antes de alterar a arquitetura ou o comportamento visível ao público. - Diferencie o código-fonte principal, os recursos de tempo de execução, as traduções, os testes, a documentação, os subprojetos e o código externo incorporado. - Não pressuponha o compilador, sistema operacional, conjunto de recursos ou ambiente gráfico mais recente. - Mantenha o comportamento coerente entre as variantes suportadas, a menos que a alteração seja controlada explicitamente por uma chave de recurso. ## Compile e teste a configuração afetada sem novos avisos - Use o caminho de compilação documentado para a plataforma e a cadeia de ferramentas atuais. - Regenere declarações de funções ou outras interfaces derivadas por meio do respectivo gerador, em vez de editar manualmente a saída gerada. - Durante a iteração, execute o arquivo de teste específico e examine tanto a saída de mensagens quanto o registro detalhado dos testes. - Antes do envio, exija uma compilação limpa, sem novos avisos, os testes relevantes aprovados e um estilo de código-fonte compatível com o arquivo editado. - Quando os procedimentos de compilação variarem entre plataformas, consulte o guia de instalação da plataforma em vez de adaptar comandos por suposição. - Amplie os testes quando código compartilhado, combinações de recursos ou arquivos de tempo de execução forem afetados. ## Regenere arquivos gerados só pelo gerador e respeite os responsáveis pelos arquivos - Descubra quais diretórios são gerados, importados de uma fonte externa, compartilhados com projetos relacionados ou mantidos por uma pessoa responsável designada. - Altere um arquivo gerado somente quando sua fonte mudar e mantenha qualquer regeneração não relacionada fora de patches funcionais. - Encaminhe alterações em recursos de tempo de execução mantidos pelo fluxo documentado da pessoa responsável, sem contornar essa responsabilidade. - Atualize as datas ou descrições de alteração obrigatórias ao editar arquivos de tempo de execução e ajuda que são distribuídos. - Adicione a entrada de rastreamento de patches exigida pelo repositório para alterações no código-fonte principal, exceto quando houver uma exceção explícita de diretório. - Nunca misture em um único patch atualizações de código externo, ruído gerado, traduções e limpeza de código-fonte não relacionada. ## Escreva no assunto do commit o problema, não a solução - Siga exatamente a estrutura de assunto e corpo de patch definida pelo repositório. - Declare o problema no assunto, não a implementação da solução. - Escreva uma frase completa para o problema e uma frase concisa para a solução, com a atribuição e a pontuação obrigatórias. - Quando o formato exigir, coloque a explicação opcional após o cabeçalho obrigatório de problema e solução, usando prosa em vez de listas. - Rotule referências corrigidas, encerradas e relacionadas de acordo com seus significados distintos. - Inclua a certificação obrigatória da pessoa desenvolvedora e reconheça a assistência de IA somente pelo mecanismo de coautoria aceito. ## Siga o estilo C existente e evite sintaxe que compiladores antigos não aceitam - Preserve o recuo lógico de 4 espaços, respeitando as regras específicas de cada arquivo para tabulações ou somente espaços. - Coloque as chaves de abertura em linhas próprias para funções e estruturas de controle. - Formate as definições de função com o tipo de retorno e o nome da função na disposição estabelecida pelo repositório. - Siga a posição das declarações no arquivo ao redor, em vez de modernizá-la de modo oportunista. - Use somente a linguagem C de base documentada e os recursos mais recentes que tenham sido aprovados; não introduza construções incompatíveis com compiladores antigos. - Execute qualquer formatador específico do arquivo após a edição e examine suas diferenças. ## Use os tipos do projeto e passe aos auxiliares o comprimento de string já conhecido - Use o sufixo de tipo personalizado do repositório e evite sufixos reservados por padrões do sistema. - Preserve a migração booleana em andamento: use de forma coerente, dentro de um patch, a forma booleana estabelecida localmente e evite conversões em massa. - Inicialize variáveis locais quando a primeira atribuição não for evidente, mas não adicione inicializações redundantes que possam ocultar uma leitura não inicializada. - Use o auxiliar de comprimento literal para literais de string e o formatador que retorna o comprimento quando o tamanho gravado for necessário. - Quando o comprimento de uma string já for conhecido, passe-o à operação ciente do comprimento, em vez de percorrê-la novamente. - Mantenha cada ponteiro para um buffer de bytes junto de seu comprimento `size_t`; use tipos inteiros mais estreitos somente quando uma interface legada exigir. ## Gerencie a memória com os wrappers do projeto e libere-a em todo erro - Prefira as funções envoltórias do repositório às operações diretas de alocação, liberação, cópia, movimentação, caracteres e espaços em branco da biblioteca padrão. - Escolha as funções envoltórias pelo tratamento documentado de valores nulos, falta de memória, sobreposição, codificação e consistência entre plataformas. - Verifique explicitamente se o divisor não é zero antes de cada divisão, mesmo que uma condição composta anterior pareça garantir isso. - Para cada nova alocação, verifique os caminhos de limpeza em caso de sucesso, retorno antecipado e cada ramo de erro. - Mantenha os tamanhos de buffer em bytes e torne explícito o comportamento de truncamento, terminação e comprimento gravado. - Não substitua uma função envoltória mais segura do projeto por uma chamada genérica de biblioteca apenas por ela ser mais familiar. ## Siga as regras de nomes e macros e mantenha os arquivos de make portáteis - Siga as restrições de nomes reservados, identificadores proibidos, limites de comprimento de nomes de função, espaçamento e a regra de uma instrução por linha. - Use o prefixo estabelecido para recursos e a convenção de macros em maiúsculas. - Teste macros de recurso com o padrão condicional suportado pelo repositório. - Mantenha os arquivos principais de compilação dentro do dialeto portátil de make documentado; evite extensões de atribuição, padrão, shell e condicionais específicas de uma implementação. - Reutilize os tipos de string e bytes do projeto e suas macros correspondentes. - Leia as referências oficiais de estilo antes de introduzir um novo identificador, macro ou regra de compilação. ## Escreva scripts de execução que funcionem também em ambientes e derivações relacionados - Use o estilo de script atual em novos arquivos, considerando a compatibilidade com ambientes de execução e derivações relacionadas. - Quando a compatibilidade for incerta, pergunte antes de adotar uma construção mais recente da linguagem. - Siga as convenções de nomes de variáveis locais nos testes de script. - Não repita uma chave de recurso em testes individuais quando o arquivo já controlar esse recurso no nível superior. - Se o arquivo não tiver um controle no nível superior, adicione um controle específico somente aos testes que exigirem o recurso opcional. - Mantenha alterações em scripts de tempo de execução separadas de uma modernização não relacionada da linguagem principal. ## Escreva testes de regressão que reproduzam o defeito relatado - Prefira uma asserção determinística a um teste que apenas verifique que o programa não falha. - Para defeitos de renderização, adicione uma comparação de captura de tela; para dados incorretos, verifique a saída exata. - Adicione cobertura abrangente para o novo comportamento, de preferência em um arquivo de teste relevante já existente. - Ao corrigir um defeito relatado, reproduza o cenário original, em vez de apenas um caso sintético simplificado. - Use os auxiliares padrão para sessões de terminal, despejos de tela, carregamento bem-sucedido de scripts e falhas esperadas no carregamento de scripts. - Coloque testes de sintaxe e recuo dos recursos de tempo de execução em suas suítes dedicadas. ## Atualize a documentação de ajuda no mesmo patch e mantenha o formato dela - Atualize a documentação voltada à pessoa usuária no mesmo patch de qualquer alteração de opção ou recurso. - Atualize o cabeçalho de alterações do arquivo de ajuda ao editar a documentação existente. - Preserve o formato oficial da ajuda para cabeçalhos de arquivo, linhas de modo, largura, alinhamento por tabulações, tags exclusivas, referências cruzadas, títulos, exemplos de código e notação realçada. - Use a operação segura de retabulação e examine suas diferenças; não force uma reescrita ampla de espaços em branco. - Mantenha as tags de link exclusivas em todo o conjunto e adicione um prefixo às tags específicas de extensões quando necessário. - Prefira linguagem neutra em relação a gênero em textos novos ou alterados, sem reescrever texto não afetado apenas para essa finalidade. ## Verifique primeiro a fase de versões e mantenha o comportamento obsoleto acessível - Determine se o projeto está em um ciclo de desenvolvimento ou em um período de estabilidade antes de propor o escopo. - Durante um período de estabilidade, limite as alterações aceitas a correções claras de defeitos, correções de segurança, documentação, traduções e manutenção de recursos de tempo de execução. - Não introduza novos recursos nem alterações no núcleo incompatíveis com versões anteriores durante a estabilidade. - Preserve o comportamento publicado do núcleo entre versões secundárias. - Mantenha o comportamento obsoleto acessível pela configuração, documente-o como obsoleto, permita desativá-lo durante a compilação quando houver suporte e remova-o somente em um ciclo posterior permitido. - Trate os recursos de tempo de execução conforme sua flexibilidade de manutenção documentada, sem enfraquecer as garantias do núcleo. ## Envie patches em que cada commit compile e passe nos testes sozinho - Leia a política de segurança antes de relatar uma possível vulnerabilidade ou alterar código sensível à segurança. - Garanta que estejam completos o formato do commit, a compilação limpa, os testes relevantes, a cobertura de regressão, a documentação e a certificação. - Limite as diferenças ao problema declarado: sem alterações isoladas de espaços, refatorações não relacionadas ou saída gerada alheia. - Em uma série com vários patches, exija que cada commit compile e passe em seus próprios testes de forma independente. - Não deixe um commit intermediário intencionalmente quebrado para ser reparado por outro posterior; combine-os. - Confirme que o comportamento documentado e o comportamento imposto ainda coincidem e descreva alterações intencionais no registro de problema e solução. ## Faça a menor mudança possível e pergunte antes de agir fora da árvore de trabalho - Faça a menor alteração que alcance o objetivo e siga o código ao redor, em vez de impor uma melhoria ampla. - Divida um patch que resolva vários problemas independentes. - Se um patch tratar apenas um sintoma, informe o problema mais profundo e a limitação de escopo escolhida. - Reproduza um defeito antes de afirmar que ele existe e leia a implementação antes de afirmar o que o código faz. - Não dependa do conteúdo de arquivos lembrado quando o código-fonte atual estiver disponível. - Confirme com a pessoa usuária antes de instalar pacotes, modificar arquivos fora da árvore de trabalho, enviar branches ou usar operações de rede.