Alterar uma biblioteca de contratos inteligentes sem quebrar os projetos que a usam

## Projetar para os projetos que herdam a biblioteca e combinar mudanças antes em uma issue - Este repositório é uma biblioteca de contratos inteligentes: contratos abstratos e bibliotecas reutilizáveis feitos para serem herdados e estendidos por projetos downstream, não uma aplicação implantada. A maioria das convenções existe porque o código é uma base para outros. - Como os herdeiros dependem dela, projete pensando em extensão: as funções devem ser sobrescrevíveis onde a extensão é esperada, os tipos de argumento não devem restringir demais os herdeiros, e a API pública não deve impor um contexto de chamada específico aos contratos filhos. - Leia primeiro o guia oficial de contribuição humana do repositório; ele é a fonte da verdade. Um guia para assistente de IA cobre apenas o que é específico do trabalho assistido e as convenções não documentadas em outro lugar. Onde os dois divergirem, a especificação humana prevalece. - Discuta qualquer mudança não trivial em uma issue antes de abrir um pull request. Obtenha primeiro um acordo sobre a direção em vez de implementar sem solicitação, depois abra o PR dentro desse escopo acordado. ## Alterar o arquivo dono do comportamento e nunca editar à mão arquivos gerados - Um repositório de biblioteca tem várias camadas distintas: código-fonte da biblioteca (a API pública), mocks usados só em testes que a espelham, definições de interface originais, wrappers gerados automaticamente, especificações de verificação formal, fontes de documentação e relatórios históricos de auditoria. Identifique qual camada é dona de um arquivo antes de editá-lo, e altere a camada dona do comportamento em vez de uma camada adjacente. Uma única tarefa pode tocar várias camadas ao mesmo tempo, então não presuma que uma mudança é "só código" ou "só documentação" sem verificar. - Nunca edite manualmente um arquivo gerado automaticamente ou gerenciado por ferramenta. Um arquivo gerado proceduralmente a partir de um template traz um cabeçalho informando isso: em vez disso, edite o template e regenere, porque o CI garante a atualização com uma verificação de diff de geração e edições manuais são sobrescritas. Wrappers gerados automaticamente costumam estar no gitignore e são reconstruídos sob demanda. - Deixe os metadados mantidos por ferramentas para a própria ferramenta. Uma linha de cabeçalho "última versão atualizada" por arquivo é mantida automaticamente a partir do histórico de controle de versão pela ferramenta de release; não a adicione nem a edite. Sua responsabilidade se limita ao que a ferramenta não gerencia, como a linha do identificador de licença. ## Deixar para o linter as regras de nomes e visibilidade, sem repeti-las em revisões - Um linter configurado já aplica as convenções mecânicas no código-fonte da biblioteca (mocks e testes costumam ser isentos): variáveis de estado são privadas por padrão, com `constant` e `immutable` como únicas exceções; um prefixo de underscore é associado à visibilidade, então estado e funções privados e internos levam um underscore no início enquanto membros públicos e externos não; nomes de interface são prefixados com `I`; contratos e eventos usam CapWords; parâmetros e modifiers usam mixedCase; bibliotecas expõem apenas funções internal ou private. - Se uma regra de lint já detecta um problema, não gaste tokens explicando isso em uma revisão de código; corrija e siga em frente. Repetir uma regra já imposta pelo lint em um comentário de revisão é ruído, não sinal. ## Seguir as regras de versão do compilador e de imports que o linter não detecta - Piso do pragma do compilador: não escolha manualmente a versão mínima. Execute a ferramenta de minimização de pragma do projeto, que percorre o grafo de dependências, compila contra cada versão candidata do compilador e grava de volta a menor versão que funciona por arquivo (um prefixo `>=` para interfaces, `^` para implementações e bibliotecas). Elevar o piso de forma casual pode introduzir opcodes não suportados em algumas chains alvo, então a saída da ferramenta é a resposta segura. - Os imports devem ser 100% nomeados, com chaves, e relativos dentro da árvore de código-fonte. Nada de imports com wildcard. - A ordem de herança deve ser globalmente consistente. Se você alterar uma lista `is A, B, C`, recompile e execute a verificação de ordem de herança antes de dar push. - Entradas de changelog: toda mudança que altera o comportamento do contrato precisa de uma. Pule apenas para edições somente de documentação, refatorações internas sem efeito visível para o usuário, ou tarefas puramente estruturais do repositório. ## Não alterar funções nem o layout de armazenamento existentes e adicionar poucas dependências - Contratos lançados são herdados downstream e frequentemente transpilados para uma variante upgradeable separada. Não altere as assinaturas de funções públicas ou externas existentes, a forma de eventos ou errors existentes, nem o layout de armazenamento de contratos existentes. Faça mudanças aditivas; deprecie em vez de excluir. Uma breaking change é uma decisão dos mantenedores vinculada a um major release, nunca algo a ser introduzido durante o trabalho de rotina. - Mantenha a superfície de dependências mínima. Reutilize os utilitários já existentes na biblioteca antes de buscar algo externo. Não adicione um pacote de terceiros ou um novo import externo sem aprovação dos mantenedores; código que realmente precisa de dependências de terceiros mais pesadas pertence a um repositório separado de comunidade ou extensões, não à biblioteca principal. ## Revisar à mão o código de criptografia e de slots de armazenamento, onde a IA costuma errar - Nessas áreas, as sugestões de IA são frequentemente plausíveis, mas erradas. Leia o código ao redor e re-derive a afirmação antes de aceitar qualquer mudança: - Criptografia: hashing, ECDSA, separadores de domínio de dados tipados (EIP-712), esquemas de assinatura e matemática de pairing ou BLS. - Derivações de storage-slot, como slots namespaced (ERC-7201): recalcule com o helper de derivação canônico e compare com a constante declarada. A fórmula no comentário inline é obrigatória, não decorativa. - Layout de armazenamento para contratos processados por proxy ou transpiler: adicionar, remover ou reordenar campos quebra proxies já implantados. Leia o diff de storage layout mesmo que o CI também o execute. - `delegatecall`, assembly inline e segurança de memória: verifique se qualquer anotação memory-safe é honesta e se o uso de stack e scratch-space é limitado. - Blocos `unchecked`: re-derive o argumento de impossibilidade de overflow para cada caminho de código. O comentário de justificativa inline é o contrato que você deve sustentar. - Autorização de upgrade: um hook de autorização de upgrade fica vazio na base por design, então todo override deve restringir quem pode chamá-lo. - Construtores de implementação proxy: confirme que os initializers estão desabilitados (por exemplo, uma chamada disable-initializers) nos alvos de implementação UUPS ou transparent-proxy. ## Deixar para pessoas as mudanças na API pública e os julgamentos de segurança - Adicionar ou renomear API pública, ou decidir se uma funcionalidade pertence à biblioteca: abra uma issue e obtenha primeiro uma decisão dos mantenedores. - Avaliações de segurança e opiniões de auditoria: deixe a cargo de auditores humanos em vez de afirmar que um contrato é seguro. - Novos padrões de interface sem orientação explícita. - Reestruturar testes sem uma mudança correspondente no contrato. - Nunca invente recompensas de segurança. Não afirme, insinue ou invente um programa de bug bounty, valor de recompensa ou elegibilidade. Referencie apenas um programa oficialmente documentado, se genuinamente existir.