É inevitável fazer mudanças interruptivas no Bazel. Precisaremos mudar os 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 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 alteração interruptiva no Bazel para obedecer a essa política.
Siga a política de documentos de design.
Problema no GitHub
Registre um problema no GitHub (em inglês) no repositório do Bazel. Veja um exemplo.
Recomendamos o seguinte:
O título começa com o nome da sinalização, que começa com
incompatible_.Adicione o rótulo
incompatible-change.Ela contém uma descrição da mudança e um link para os documentos de design relevantes.
A descrição contém um roteiro de migração para explicar aos usuários como atualizar o código. O ideal é que, quando a alteração 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 receberão se não migrarem. Isso tornará o problema do GitHub mais detectável nos mecanismos de pesquisa. Garanta que a mensagem de erro seja útil e útil. Quando possível, a mensagem de erro precisa incluir o nome da sinalização incompatível.
Para a ferramenta de migração, considere contribuir para o
Buildifier.
Ele pode aplicar correções automáticas a arquivos BUILD, WORKSPACE e .bzl.
Também é possível que ele exiba avisos.
Implementação
Crie uma nova sinalização no Bazel. O valor padrão precisa ser falso. O texto de ajuda deve conter o URL do problema do GitHub. Quando o nome da sinalização começa com incompatible_, ele precisa de tags de metadados:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Na descrição da confirmação, adicione um breve resumo da sinalização.
Adicione também RELNOTES: no seguinte formato:
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 uma janela de confirmações em que o código seja inconsistente com os documentos. Como nossa documentação é controlada, as alterações nos documentos não serão liberadas prematuramente.
Rótulos
Depois que a confirmação for mesclada 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 sinalização e os usuários não tiverem previsão de migração,
remova-as migration-ready.
Se você pretende virar a sinalização 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 geralmente são
dependências 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.
Veja aqui como esse pipeline funciona.
Nossa equipe de suporte do desenvolvedor monitora o marcador migration-ready. Depois que você adicionar esse rótulo ao problema do GitHub, ele vai processar o seguinte:
Crie um comentário no problema do GitHub para acompanhar a lista de falhas e projetos downstream que precisam ser migrados (veja o exemplo).
Registre problemas no GitHub para notificar os proprietários de cada projeto downstream corrompido por sua 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 é totalmente de responsabilidade do autor da alteração incompatível, mas é possível fazer o seguinte para acelerar a migração e facilitar a vida dos usuários do Bazel e da equipe do Bazel Green.
Envie PRs para corrigir projetos downstream.
Entre em contato com a comunidade do Bazel se precisar de ajuda para fazer a migração. Por exemplo: SIG dos autores das regras do Bazel.
Levantando a bandeira
Antes de mudar o valor padrão da sinalização para "true", confirme o seguinte:
Os repositórios principais no ecossistema são migrados.
No pipeline
bazelisk-plus-incompatible-flags, a sinalização 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 dos usuários foram resolvidas.
Quando a sinalização estiver pronta para ser virada no Bazel, mas bloqueada na migração interna no Google, defina o valor da sinalização como "false" no arquivo blazerc interno para desbloquear. Ao fazer isso, podemos garantir que os usuários do Bazel dependam do novo comportamento por padrão o mais cedo possível.
Ao mudar a sinalização padrão para verdadeira, 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 detailsVocê pode incluir outras informações no restante da descriçã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 rastrear a remoção da sinalização.
Como remover a sinalização
Depois que a sinalização é virada no HEAD, ela deve ser removida do Bazel em algum momento. Quando você planeja remover a sinalização incompatível:
- Considere deixar mais tempo para os usuários migrarem se for uma alteração importante e incompatível. O ideal é que a sinalização esteja disponível em pelo menos uma versão principal.
- Para a confirmação que remove a sinalização, use
Fixes #abcna descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.