Altere uma biblioteca Go pública sem quebrar o código de quem a usa

## Antes de alterar o código, verifique as versões de Go suportadas e as ramificações Trate a correção, a compatibilidade retroativa e as especificações externas aplicáveis como critérios principais de aceitação. Antes de alterar o código, identifique: - a ramificação de desenvolvimento ativa e a ramificação estável de manutenção mais recente; - a versão mínima do Go suportada para os usuários; - a versão mais recente do Go e a cadeia de ferramentas necessárias para desenvolver o repositório; - quais pacotes formam a API pública coberta pela garantia de compatibilidade; - quais pacotes internos ou experimentais podem ser importados e são usados na prática, embora estejam fora das garantias de versionamento semântico. Não presuma que “não coberto pelo versionamento semântico” significa “seguro para causar incompatibilidade”. Sinalize alterações de comportamento ou de API que possam afetar usuários reais. De acordo com a política do repositório, direcione novos recursos à ramificação de desenvolvimento e correções à ramificação estável apropriada. Nos pacotes públicos, evite APIs da biblioteca padrão e recursos da linguagem posteriores à versão mínima declarada do Go. Mantenha a verificação de compatibilidade executável durante a compilação, para que recursos não suportados falhem cedo em vez de chegar aos usuários. ## Execute verificações e testes com as ferramentas do projeto Use o executor de tarefas e o formatador definidos pelo projeto, em vez de substituí-los por comandos familiares. O objetivo de verificação padrão deve combinar compilação, verificações de licença, formatação e módulos, lint e testes rápidos. Mantenha dois níveis de testes: - uma suíte curta com detecção de condições de corrida para retorno rápido; - uma suíte completa de integração com as dependências de serviço exigidas pelo repositório e um tempo limite ampliado. Se os testes de integração compartilharem o estado do servidor, execute a suíte completa em série e nunca aumente o paralelismo apenas para reduzir o tempo de execução. Permita configurar os endpoints dos serviços e preserve um valor local padrão documentado. Execute verificações de lint ou compilação em várias arquiteturas quando o comportamento de baixo nível depender da arquitetura. Em especial, verifique alvos de 32 bits quando houver acesso atômico: campos de 64 bits acessados atomicamente devem ter alinhamento seguro, por exemplo ficando no início de uma estrutura ou usando wrappers atômicos tipados. ## Siga os padrões da biblioteca para erros e API pública Respeite os padrões estabelecidos no repositório: - encapsule erros com contexto usando `%w` e compare-os com `errors.Is` ou `errors.As`, em vez de procurar correspondência no texto da mensagem; - use `context.Context` como primeiro argumento de todo método público bloqueante e derive os prazos do contexto do chamador, em vez de criar temporizadores independentes de relógio que concorram com ele; - use tipos de documento ordenados para comandos ou dados em que a ordem das chaves seja relevante, tipos semelhantes a mapas apenas quando a ordem realmente não importar e representações de baixo nível baseadas em sequências de bytes somente em caminhos críticos devidamente justificados; - use palavras completas nos identificadores exportados, adicione comentários de documentação com o nome como sujeito e siga o padrão de builder ou setter do projeto para novas opções. Preserve a organização atual dos pacotes e as decisões de migração. Não restaure caminhos de importação retirados nem abstrações públicas obsoletas. Quando o monitoramento de comandos ou os diagnósticos puderem observar trocas de autenticação, adicione os comandos que lidam com credenciais à política de ocultação antes de expor os eventos. Dependências nativas e etiquetas de compilação específicas de um recurso devem continuar explícitas nas instruções de configuração e teste. ## Separe testes unitários e de integração e execute os que a mudança exige Coloque testes unitários ao lado da implementação e testes de integração na área de integração do repositório. Use os auxiliares de asserção do projeto e prefira verificações semânticas, como `ErrorIs`, a asserções por substring. Para comportamentos de integração, use a estrutura de testes padrão com reconhecimento de topologia para configurar a implantação, injetar pontos de falha e capturar eventos. Mantenha os dados de teste da especificação no local designado, inicialize os submódulos ou as fontes de dados necessários após clonar o repositório e numere os casos de teste descritivos de acordo com a especificação aplicável quando a rastreabilidade for importante. Antes da revisão, execute o objetivo de verificação padrão. Execute a suíte completa em série quando a alteração afetar o comportamento de integração ou o estado compartilhado do servidor. A aprovação de um teste unitário restrito não é evidência suficiente para alterações sensíveis a várias arquiteturas, à compatibilidade ou às especificações. ## Prepare um pull request com os resultados dos testes e o impacto na compatibilidade Use o prefixo obrigatório do item de trabalho nas mensagens de commit e nos títulos de pull request. O pull request deve explicar o comportamento visível ao usuário, o impacto na compatibilidade, as evidências dos testes e a escolha da ramificação. Adicione evidências específicas da alteração: - em alterações na API pública, gere o relatório de API do repositório e inclua-o no pull request; - em alterações incompatíveis visíveis ao usuário, atualize o guia de migração correspondente; - em trabalhos de conformidade com especificações, cite o requisito exato atendido pela implementação; - em alterações de pacotes experimentais que possam ser importados, indique explicitamente as incompatibilidades, mesmo quando o versionamento semântico não exigir isso. Não apresente uma alteração como pronta apenas porque ela compila localmente. Para estar pronta, ela deve passar pelas verificações padrão do repositório e por todas as barreiras de compatibilidade, integração, API e especificação diretamente aplicáveis.