É inevitável que façamos mudanças drásticas no Bazel. Vamos precisar mudar nossos designs e corrigir as coisas que não funcionam. No entanto, precisamos garantir que a comunidade e o ecossistema do Bazel possam acompanhar. Para isso, o projeto do Bazel adotou uma política de compatibilidade com versões anteriores. Este documento descreve o processo para que os colaboradores do Bazel façam uma mudança importante no Bazel para aderir a essa política.
Siga a política de documentos de design.
Problema no GitHub
Registre um problema no GitHub no repositório do Bazel. Confira o exemplo.
Recomendamos que você:
O título começa com o nome da sinalização (que começa com
incompatible_).Você adiciona o rótulo
incompatible-change.A descrição contém uma descrição da mudança e um link para documentos de design relevantes.
A descrição contém uma receita de migração para explicar aos usuários como atualizar o código. O ideal é que, quando a mudança for mecânica, inclua um link para uma ferramenta de migração.
A descrição inclui um exemplo da mensagem de erro que os usuários vão receber se não migrarem. Isso vai tornar o problema do GitHub mais detectável pelos motores de pesquisa. Verifique se a mensagem de erro é útil e pode ser usada. Quando possível, a mensagem de erro deve incluir o nome da flag incompatível.
Para a ferramenta de migração, considere contribuir com o
Buildifier.
Ele pode aplicar correções automáticas a arquivos BUILD, WORKSPACE e .bzl.
Ele também pode gerar alertas.
Implementação
Crie uma nova flag no Bazel. O valor padrão precisa ser falso. O texto de ajuda
precisa conter o URL do problema do GitHub. Como o nome da flag começa com
incompatible_, ele precisa de tags de metadados:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Na descrição do commit, adicione um breve resumo da flag.
Adicione também RELNOTES: no seguinte formulário:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
A confirmação também precisa atualizar a documentação relevante para que não haja janelas de confirmação em que o código seja inconsistente com os documentos. Como nossa documentação é versionada, as mudanças nos documentos não são lançadas prematuramente.
Rótulos
Depois que o commit for mesclado e a mudança incompatível estiver pronta para ser adotada, adicione o rótulo
migration-ready
ao problema do GitHub.
Se um problema for encontrado com a flag e os usuários ainda não precisarem migrar:
remova as flags migration-ready.
Se você planeja ativar a flag na próxima versão principal, adicione o rótulo "breaking-change-X.0" ao problema.
atualização de repositórios.
O Bazel CI testa uma lista de projetos importantes em
Bazel@HEAD + Downstream. A maioria delas costuma ser
dependência de outros projetos do Bazel. Portanto, é importante migrá-las para desbloquear a migração para a comunidade em geral. Para monitorar o status da migração desses projetos, use o pipeline bazelisk-plus-incompatible-flags.
Confira como esse pipeline funciona aqui.
Nossa equipe de suporte a desenvolvedores monitora o rótulo migration-ready. Depois de adicionar esse rótulo ao problema do GitHub, ele vai fazer o seguinte:
Crie um comentário no problema do GitHub para acompanhar a lista de falhas e projetos dependentes que precisam ser migrados (confira o exemplo).
Envie problemas do GitHub para notificar os proprietários de todos os projetos downstream corrompidos pela mudança incompatível (confira o exemplo).
Fazer o acompanhamento para garantir que todos os problemas sejam resolvidos antes da data de lançamento desejada
A migração de projetos no pipeline downstream NÃO é totalmente responsabilidade do autor da mudança incompatível, mas você pode fazer o seguinte para acelerar a migração e facilitar a vida dos usuários do Bazel e da equipe verde do Bazel.
Envie PRs para corrigir projetos downstream.
Entre em contato com a comunidade do Bazel para receber ajuda com a migração (por exemplo, Bazel Rules Authors SIG).
Como inverter a bandeira
Antes de definir o valor padrão da flag como "true", verifique se:
Os repositórios principais do ecossistema são migrados.
No pipeline
bazelisk-plus-incompatible-flags, a flag precisa aparecer emThe following flags didn't break any passing Bazel team owned/co-owned projects.Todos os problemas na lista de verificação são marcados como corrigidos/fechados.
As dúvidas e preocupações do usuário foram resolvidas.
Quando a flag estiver pronta para ser invertida no Bazel, mas bloqueada na migração interna do Google, defina o valor da flag como "false" no arquivo blazerc interno para desbloquear a inversão da flag. Ao fazer isso, podemos garantir que os usuários do Bazel dependam do novo comportamento por padrão o mais rápido possível.
Ao mudar o padrão da flag para "true", faça o seguinte:
- Use
RELNOTES[INC]na descrição da confirmação, com o seguinte formato:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsÉ possível incluir outras informações no restante da descrição da confirmação. - Use
Fixes #xyzna descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada. - Revise e atualize a documentação, se necessário.
- Registre um novo problema
#abcpara acompanhar a remoção da flag.
Como remover a sinalização
Depois que a flag for invertida no HEAD, ela será removida do Bazel. Quando você planeja remover a flag incompatível:
- Considere deixar mais tempo para os usuários migrarem se for uma mudança importante e incompatível. O ideal é que a flag esteja disponível em pelo menos uma versão principal.
- Para a confirmação que remove a flag, use
Fixes #abcna descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.