É inevitável fazer mudanças interruptivas no Bazel. Teremos que alterar nossos designs e corrigir as coisas que não funcionam muito bem. No entanto, precisamos para garantir que o ecossistema da comunidade e do Bazel acompanhe esse processo. Para isso, O projeto do Bazel adotou uma política de compatibilidade com versões anteriores. Este documento descreve o processo para os colaboradores do Bazel fazerem uma interrupção mudança no Bazel para aderir a essa política.
Siga a política de documentos de design.
Registre um problema no GitHub (link em inglês).
Problema no GitHub
Registre um problema no GitHub (em inglês) no repositório do Bazel. Confira um exemplo.
Recomendamos o seguinte:
O título começa com o nome da sinalização (o nome da sinalização começa com
incompatible_).Você adiciona o rótulo
incompatible-changeA descrição contém uma descrição da mudança e um link para documentos de design.
A descrição contém um roteiro de migração, para explicar aos usuários como eles devem e atualizar o código. O ideal é que, quando a mudança for mecânica, inclua um link para um ferramenta de migração.
A descrição inclui um exemplo da mensagem de erro que os usuários receberão se mas não migram. Isso tornará o problema do GitHub mais detectável mecanismos de pesquisa. Verifique se a mensagem de erro é útil e acionável. Quando possível, a mensagem de erro deve incluir o nome do elemento incompatível .
Na ferramenta de migração, considere contribuir para
Buildifier.
Ele aplica correções automáticas a arquivos BUILD, WORKSPACE e .bzl.
Além disso, ela pode informar avisos.
Implementação
Crie uma nova flag no Bazel. O valor padrão precisa ser falso. O texto de ajuda
deve conter o URL do problema no GitHub. Como o nome da sinalização 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 formato:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
O commit também precisa atualizar a documentação relevante para que não haja Janela de commits em que o código é inconsistente com os documentos. Como nossos documentação com controle de versão, as alterações nos documentos não serão aplicadas inadvertidamente lançado prematuramente.
Rótulos
Depois que a confirmação for mesclada e a mudança incompatível estiver pronta para ser adotada, adicione o marcador
migration-ready
para o problema do GitHub.
Se um problema for encontrado com a sinalização e os usuários não precisarem migrar ainda:
remova as sinalizações migration-ready.
Se você planeja alterar a flag na próxima versão principal, adicione o rótulo "breaking-change-X.0" para resolver o problema.
atualização de repositórios.
A CI do Bazel testa uma lista de projetos importantes em
Bazel@HEAD + Downstream A maioria deles é frequentemente
dependências de outros projetos do Bazel. Por isso, é importante migrá-los para possibilitar a migração para a comunidade em geral. Para monitorar o status da migração desses projetos, use o pipeline bazelisk-plus-incompatible-flags.
Veja aqui como esse pipeline funciona.
Nossa equipe de suporte ao desenvolvedor monitora o rótulo migration-ready. Depois que você adicionar esse rótulo ao problema do GitHub, ele lidará com o seguinte:
Crie um comentário no problema do GitHub para rastrear a lista de falhas e projetos downstream que precisam ser migrados (veja o exemplo).
Registre problemas no GitHub para notificar os proprietários de todos os projetos downstream corrompidos pela alteração incompatível (veja o exemplo).
Faça o acompanhamento para garantir que todos os problemas sejam resolvidos antes da data de lançamento prevista
A migração de projetos no pipeline downstream NÃO é inteiramente 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 do Bazel Green Team.
Envie PRs para corrigir projetos downstream.
Entre em contato com a comunidade do Bazel para receber ajuda na migração (por exemplo, Bazel Rules Authors SIG).
Invertendo a bandeira
Antes de alterar o valor padrão da flag para "true", verifique se:
Os repositórios principais do ecossistema são migrados.
No pipeline
bazelisk-plus-incompatible-flags, a sinalização vai 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 preocupações e dúvidas dos usuários foram resolvidas.
Quando a flag estiver pronta para ser ativada no Bazel, mas for bloqueada na migração interna no Google, defina o valor dela como "false" no arquivo blazerc interno para desbloqueá-la. Ao fazer isso, os usuários do Bazel precisam depender do novo comportamento por padrão o mais cedo possível.
Ao alterar o padrão de sinalização para verdadeiro:
- Use
RELNOTES[INC]na descrição do commit com o formato:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsÉ possível incluir mais informações no restante da descrição da confirmação. - Use
Fixes #xyzna descrição para que o problema do GitHub seja encerrado quando o commit for mesclado. - Revise e atualize a documentação, se necessário.
- Registre um novo problema
#abcpara rastrear a remoção da sinalização.
Como remover a sinalização
Depois que a flag é invertida em HEAD, ela precisa ser removida do Bazel. Quando você planeja remover a flag incompatível:
- Considere deixar mais tempo para os usuários migrarem se for uma grande mudança incompatível. O ideal é que a sinalização esteja disponível em pelo menos uma versão principal.
- Para o commit que remove a flag, use
Fixes #abcna descrição. para que o problema no GitHub seja encerrado quando a confirmação for mesclada.