Altere uma biblioteca de dados multilíngue sem quebrar formatos de arquivo nem APIs

## Conheça o núcleo nativo e as vinculações leves para outras linguagens Trate o repositório como um único núcleo nativo com vinculações leves para outras linguagens. O núcleo controla o comportamento dos formatos de dados, a codificação, a compactação, os arquivos, os índices, a E/S, o armazenamento de objetos, a álgebra linear, as operações com tabelas, os domínios opcionais, a infraestrutura de testes e as ferramentas de desenvolvimento. As vinculações expõem esse comportamento sem duplicar a validação nem a lógica de negócio. Preserve as principais características da arquitetura: E/S assíncrona, memória colunar nativa, gravações versionadas acompanhadas por manifestos, codificações orientadas à carga de trabalho e uma única abstração de armazenamento para repositórios de objetos locais e remotos. Leia o guia do repositório e o guia de cada linguagem ou diretório afetado antes de planejar comandos ou alterações de código. As regras específicas de cada diretório refinam o contrato do repositório, em vez de substituí-lo. ## Mantenha compatíveis os formatos estáveis e mude livremente os instáveis Trate todo formato declarado estável como um contrato de compatibilidade duradouro. Uma alteração em dados estáveis deve preservar tanto a compatibilidade retroativa quanto a compatibilidade futura. Trate todo formato declarado instável como descartável. Ele pode mudar livremente; não adicione código de compatibilidade, migrações, alternativas nem testes para arquivos criados por revisões instáveis anteriores. Avalie o novo trabalho de compatibilidade em relação à versão estável lançada mais recente, sem deixar de honrar todos os contratos estáveis. Estados que existem apenas no ramo de desenvolvimento atual não constituem restrições de compatibilidade. Não enfraqueça um projeto mais limpo ou completo apenas para preservar um estado intermediário ainda não lançado. ## Use os comandos e perfis de compilação documentados, sem trocar de cadeia de ferramentas Antes de executar comandos, identifique os comandos documentados de verificação, teste, análise estática, formatação, cobertura, desempenho e integração para a linguagem afetada. Use os seletores de pacotes e testes fornecidos pelo repositório, em vez de inventar um fluxo de trabalho paralelo. Não substitua o gerenciador de ambiente nem o conjunto de ferramentas porque um comando parece ausente, lento ou indisponível. Se um comando específico da linguagem falhar fora do fluxo de trabalho documentado, primeiro corrija o uso do ambiente e execute novamente o comando prescrito. Somente então conclua que uma dependência ou ferramenta está indisponível. Use os perfis de compilação definidos pelo repositório, em vez de substituições improvisadas de otimização. Meça o desempenho e faça a análise de perfil com uma compilação otimizada que preserve os símbolos de depuração. Desative a otimização durante a vinculação apenas para depuração local, medições de desempenho limitadas por E/S ou investigações de tempo de compilação nas quais ela não possa afetar o gargalo medido. Nos testes de integração, inicie apenas os serviços de dados de teste necessários, defina os valores de ambiente documentados e execute o alvo de integração designado. ## Escreva código focado que processa dados em fluxo, sem acumulá-los na memória Use inglês no código, nos exemplos e nos comentários. O código deve ser otimizado tanto para a legibilidade quanto para a execução. Adicione comentários apenas quando explicarem um motivo que não seja óbvio e remova as impressões diretas de depuração antes da revisão, substituindo-as pelo sistema estabelecido de rastreamento ou registro. Extraia a lógica repetida em dois ou mais lugares para um auxiliar compartilhado. Mantenha a lógica usada uma única vez no local em que ela é chamada. Introduza um auxiliar somente quando ele reduzir de modo significativo a carga cognitiva ou eliminar duplicação substancial; não adicione um invólucro superficial que apenas renomeie ou encaminhe uma chamada. Mantenha as alterações focadas. Evite refatorações oportunistas, reformatações e ajustes cosméticos. Preserve o processamento contínuo, em vez de acumular lotes na memória, e prefira estruturas compactas de mapas de bits a conjuntos de dispersão genéricos para representar a pertença de inteiros densos. ## Mantenha as vinculações leves e marque APIs antigas como obsoletas em vez de quebrá-las Centralize a validação e a lógica no núcleo nativo e mantenha cada vinculação de linguagem como um invólucro leve. Use os mesmos nomes de parâmetros em todas as vinculações; renomeie-os em todas elas ou em nenhuma. Nunca quebre uma assinatura pública existente diretamente. Marque o método antigo como obsoleto com a anotação aceita pela linguagem e adicione um novo método. Substitua grupos de sinalizadores booleanos mutuamente exclusivos por um único parâmetro de enumeração ou modo. Quando o comportamento do núcleo mudar, atualize em conjunto cada vinculação aplicável, interface gerada, exemplo e teste de compatibilidade. Uma vinculação não deve reinterpretar silenciosamente um valor rejeitado pelo núcleo. ## Nomeie os valores pelo que são e rejeite entradas inválidas com erros claros Dê a uma variável um nome que descreva o que seu valor representa, não a forma como ele é usado. Elimine prefixos redundantes quando o tipo ou módulo que a contém já indicar o domínio. Use de modo consistente uma única forma plural aprovada nas APIs e na documentação e prefira nomes independentes do armazenamento a termos específicos de um provedor. Ao renomear um tipo, uma estrutura ou uma enumeração, atualize em conjunto os métodos, campos, variáveis, testes e a documentação. Valide as entradas nos limites da API e rejeite valores inválidos com erros descritivos. Nunca os limite nem ajuste silenciosamente. Rejeite opções mutuamente exclusivas do construtor ou da configuração quando ambas estiverem presentes. Inclua nos erros os nomes, valores, tamanhos e tipos das variáveis relevantes. ## Adicione poucas dependências e mantenha os arquivos de bloqueio sincronizados Antes de adicionar um pacote externo, prefira a biblioteca padrão ou as dependências já existentes no espaço de trabalho. Faça alterações intencionais nos arquivos de bloqueio, reverta atualizações não relacionadas e fixe a versão de uma dependência com defeito somente com um comentário que contenha um link para o problema correspondente no projeto de origem. Quando uma dependência do espaço de trabalho mudar, atualize o arquivo de bloqueio raiz e o arquivo de bloqueio de cada vinculação excluída por meio das verificações documentadas específicas de cada manifesto; em seguida, registre todas as atualizações correspondentes. Mantenha ativo o gancho de sincronização dos arquivos de bloqueio no modo desconectado. Coloque dependências opcionais ou específicas de um domínio atrás de sinalizadores de recurso. Prefira um pacote separado para funcionalidades substanciais de um domínio, para que as compilações padrão e seus consumidores não herdem código desnecessário. ## Inclua um teste em cada correção de defeito e em cada novo recurso Toda correção de defeito e toda funcionalidade requer testes correspondentes. Não aceite código sem testes. Use o recurso de testes parametrizados da linguagem quando os casos diferirem apenas pela entrada e dê nomes legíveis aos casos. Substitua impressões nos testes por asserções, pois apenas produzir uma saída não detecta regressões. Amplie um teste existente quando ele já abranger o comportamento, em vez de adicionar um arquivo de teste sobreposto. Faça as adições no local de testes estabelecido. Um teste ignorado deve conter um link para um problema de acompanhamento; nunca adicione uma anotação isolada para ignorá-lo sem uma justificativa duradoura. ## Teste com dados nulos ou vazios e com arquivos de versões estáveis antigas Inclua cenários com vários fragmentos para leituras, índices e varreduras. Nos testes de índices, cubra elementos nulos, coleções inteiramente nulas, coleções vazias e colunas nulas. Os testes de índices vetoriais devem verificar uma métrica de recall de pelo menos 0,5, em vez de apenas confirmar que a criação do índice foi bem-sucedida. Para a compatibilidade retroativa, use conjuntos de dados mantidos no repositório e produzidos por versões estáveis anteriores. Mantenha um script de geração de dados que verifique a versão produtora e copie esses dados de teste para um armazenamento temporário antes de lê-los. Não desative testes de documentação apenas para evitar a compilação. Escreva exemplos que sejam compilados dentro de um contexto com formato de função. Exclua os utilitários exclusivos de testes da cobertura por meio da anotação de cobertura aprovada pelo projeto, em vez de enfraquecer os limites mínimos de cobertura do código de produção. ## Documente cada API pública com um exemplo que compila Documente toda API pública e inclua um exemplo. Crie vínculos para os tipos e métodos relevantes e mantenha os exemplos sincronizados com as assinaturas reais sempre que o código for refatorado. Use diagramas de árvore em ASCII para estruturas hierárquicas, como camadas de codificação, formatos de arquivos e disposições de armazenamento. Siga o contrato de recuo do sistema de documentação, incluindo quatro espaços de recuo sob as diretivas de observação. Revise os comentários e a documentação antes da revisão. Uma documentação que já não compila ou menciona uma API obsoleta é um defeito de compatibilidade, não um problema cosmético. ## Rotule os problemas e passe no lint antes de abrir uma solicitação de alteração Ao criar um problema por meio de uma ferramenta de linha de comando ou API, informe explicitamente o rótulo de defeito, funcionalidade ou desempenho, pois a automação do modelo de formulário pode ser contornada. Prefixe o título com a classificação correspondente para que a automação baseada no conteúdo disponha de um sinal alternativo confiável. Use os prefixos convencionais do repositório nos títulos das alterações e acrescente um escopo quando for útil. Antes de criar ou atualizar uma solicitação de alteração, execute as verificações de análise estática exigidas para cada superfície de linguagem afetada, mesmo quando forem dispendiosas. Siga o fluxo de trabalho de ambiente do guia de cada linguagem para executar os comandos de análise estática. Se uma verificação obrigatória não puder ser executada, declare explicitamente o impedimento no resumo da solicitação de alteração, em vez de dar a entender que a validação foi concluída. ## Concentre a revisão em defeitos graves e problemas de segurança A atenção de colaboradores e mantenedores é limitada. Mantenha as revisões concisas e claras e concentre-se nos defeitos de maior gravidade, nas regressões de desempenho e nas questões de segurança. Não repita alterações detalhadas nem aquilo que já está correto. Verifique a consistência dos nomes, os padrões estabelecidos de tratamento de erros e a cobertura de testes. Indique o local afetado e explique a consequência concreta de cada constatação impeditiva.