É inevitável fazer alterações interruptivas no Bazel. Teremos que mudar nossos designs e corrigir as coisas que não funcionam muito bem. No entanto, precisamos garantir que o ecossistema da comunidade e do Bazel possa acompanhar. Para isso, o projeto Bazel adotou uma política de compatibilidade com versões anteriores (link em inglês). Neste documento, descrevemos o processo para colaboradores do Bazel fazerem uma alteração interruptiva para aderir a essa política.
Siga a política do documento de design.
Registre um problema no GitHub (em inglês).
Problema no GitHub
Registre um problema do GitHub no repositório do Bazel. Confira um exemplo.
Recomendamos que:
O título começa com o nome da flag (o nome dela 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 um roteiro de migração para explicar aos usuários como eles precisam atualizar o código. O ideal é que a mudança seja 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 tornará o problema do GitHub mais detectável pelos mecanismos de pesquisa. Certifique-se de que a mensagem de erro seja útil e possa ser transformada em ações. 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.
É possível aplicar correções automáticas aos arquivos BUILD
, WORKSPACE
e .bzl
.
Ela também pode enviar alertas.
Implementação
Crie uma nova sinalização 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 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:
neste 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 janela de confirmações em que o código fique inconsistente com os documentos. Como nossa documentação é controlada por versões, as mudanças neles não serão lançadas de forma acidental antes da hora.
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 inverter a sinalização 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. Portanto, é importante migrá-los para liberar a migração para a comunidade como um todo.
Para monitorar o status de migração desses projetos, use o
pipeline bazelisk-plus-incompatible-flags
(em inglês)
e verifique como ele funciona neste link.
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 do Bazel Green.
- Registre problemas no GitHub para notificar os proprietários dos projetos downstream corrompidos pela mudança incompatível.
- Envie PRs para corrigir projetos downstream.
- Entre em contato com a comunidade do Bazel para receber ajuda na migração, por exemplo, SIG Authors de regras do Bazel.
Virar a bandeira
Antes de mudar 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 precisa aparecer emThe following flags didn't break any passing Bazel team owned/co-owned projects
.As preocupações e dúvidas dos usuários foram resolvidas.
Quando a sinalização estiver pronta para ser ativada no Bazel, mas bloqueada na migração interna no Google, defina o valor da sinalização como "false" no arquivo blazerc
interno para desbloquear a inversão da sinalização. Ao fazer isso, é possível garantir que os usuários do Bazel dependam do novo comportamento por padrão o quanto antes.
Ao alterar o padrão da flag para "true":
- 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 mais informações no restante da descrição da confirmação. - 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 flag.
Como remover a sinalização
Depois que a sinalização é invertida em HEAD, ela precisa ser removida do Bazel. Quando você planeja remover a sinalização incompatível:
- Se essa for uma mudança muito incompatível, considere a possibilidade de deixar mais tempo para os usuários fazerem a migração. 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 #abc
na descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.