É inevitável fazer mudanças interruptivas no Bazel. Teremos que mudar nossos designs e corrigir as coisas que não funcionam bem. No entanto, precisamos garantir que o ecossistema da comunidade e do Bazel possa acompanhar. Por 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 alteração interruptiva 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 do GitHub 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çará 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 um roteiro 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 receberão se não migrarem. Isso tornará o problema do GitHub mais detectável nos mecanismos de pesquisa. Verifique se a mensagem de erro é útil e acionável. Quando possível, a mensagem de erro precisa incluir o nome da sinalização incompatível.
Para a ferramenta de migração, contribua com o
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
precisa conter o URL do problema no GitHub. Como o nome da sinalização começa com incompatible_
, ela 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
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 tem controle de versões, as mudanças não serão lançadas prematuramente por acidente.
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 ainda não precisarem migrar:
remova as sinalizações migration-ready
.
Se você planeja mudar a flag na próxima versão principal, adicione o rótulo "breaking-change-X.0" ao problema.
atualização de repositórios.
A CI do Bazel testa uma lista de projetos importantes em
Bazel@HEAD + Downstream. A maioria deles costuma ser
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
.
Confira 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 por uma mudança 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 deve 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. Assim, 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 seguinte formato:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details
Você pode incluir mais informações no restante da descrição do commit. - Use
Fixes #xyz
na 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
#abc
para 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.
- Use
Fixes #abc
na descrição da confirmação que remove a sinalização para que o problema do GitHub seja encerrado quando a confirmação for mesclada.