Tema: compatibility
-
musl versus glibc no Alpine: por que alguns binários pré-compilados, wheels Python e o comportamento de DNS diferem
O musl libc do Alpine não é compatível em nível binário com a glibc, usa um resolvedor de DNS diferente (paralelo e sem fallback para search), adota por padrão o locale C.UTF-8 em vez de uma base completa de locales e não suporta lazy binding de símbolos. Essas diferenças explicam binários ligados à glibc que não executam, wheels manylinux rejeitadas e configurações antigas de DNS que se comportam de outra forma. O gcompat consegue executar alguns binários glibc sem modificação, mas não serve para compilar software que exige os headers da glibc.
-
Protocol Buffers: números de campo, campos desconhecidos e as regras para evoluir uma mensagem
No Protocol Buffers, o número do campo, e não o nome, identifica um campo no formato binário; por isso os números nunca devem mudar nem ser reutilizados. Adicionar campos é seguro no formato binário, remover só é seguro se o número nunca for reaproveitado (o que uma instrução reserved garante), leitores antigos preservam campos desconhecidos e ampliar int32 para int64 só é seguro sob certas condições. O ProtoJSON tem regras próprias e diferentes.
-
Comparar o documento OpenAPI no CI detecta breaking changes que o code review deixa passar
Hipótese: um passo de CI que compara o documento OpenAPI de cada alteração com o da versão lançada, usando um classificador de breaking changes como o oasdiff, sinaliza campos removidos, tipos restringidos e novos parâmetros obrigatórios que a revisão humana do diff de código não vê, de modo que menos breaking changes não intencionais chegam a uma release.
-
Descontinuar uma função em uma biblioteca: avisar, documentar a substituta e remover no prazo definido
Uma descontinuação em biblioteca tem quatro partes: uma substituta que exista antes de tudo, um aviso em tempo de execução mais uma nota na documentação com a versão e a substituta, uma entrada no changelog e uma versão de remoção fixada de antemão por política. A PEP 387 exige um período de descontinuação de pelo menos dois anos no ciclo anual do Python e descreve uma descontinuação leve (soft deprecation) apenas na documentação; o Django remove os shims no mínimo duas versões de funcionalidades após o aviso.
-
Evolução de esquemas com Avro e Parquet: esquemas de leitor e de escritor, arquivos mesclados e modos de compatibilidade
O Avro resolve o esquema do escritor contra o do leitor campo a campo, preenchendo campos ausentes com os valores padrão do leitor e ignorando os desconhecidos; arquivos Parquet com esquemas diferentes, porém compatíveis, podem ser mesclados pelo mecanismo de leitura, a um certo custo; um schema registry impõe compatibilidade backward, forward ou full. Adicionar campos opcionais com valor padrão é a opção segura; renomear campos e mudar tipos não é.
-
Descontinuar um endpoint de API com os cabeçalhos Deprecation e Sunset
Anuncie o fim de vida na própria resposta: o cabeçalho Deprecation (RFC 9745) marca um recurso como descontinuado, o Sunset (RFC 8594) indica quando deixará de funcionar e um Link para a documentação explica a substituição; combine-os com o registro em log dos clientes que ainda o chamam.
-
Enums em Protocol Buffers: trate valores numéricos desconhecidos conforme o comportamento do runtime
Planeje o tratamento de enums compatível com versões futuras a partir do modo de schema escolhido e da implementação de cada linguagem.
-
Suporte a várias linhas de release: quais correções vão para onde
Uma política de suporte é uma tabela de linhas de release, cada uma com um status (feature, bugfix, somente segurança, fim de vida), e uma regra que define quais classes de correção são portadas para quais linhas. O Python mantém uma série com releases de bugfix por dois anos e releases somente de segurança por mais três; o Django porta correções críticas para o último feature release e correções de segurança e perda de dados para os dois últimos, além das linhas de suporte de longo prazo; o Rust suporta apenas a versão estável mais recente. Um projeto pequeno deve publicar a tabela e adotar por padrão a promessa mais restrita que consiga cumprir.
-
Associe cada afirmação à versão que ela cobre
Represente explicitamente o escopo de versão e recuse-se a aplicar uma afirmação da documentação atual a uma instalação desconhecida ou incompatível.
Legível por máquina: JSON