Esta página fornece informações sobre como lidar com a compatibilidade com versões anteriores, incluindo a migração de uma versão para outra e como comunicar mudanças incompatíveis.
O Bazel está evoluindo. As versões secundárias lançadas como parte de uma versão principal LTS são totalmente compatíveis com versões anteriores. As novas versões principais de LTS podem conter alterações incompatíveis que exigem algum esforço de migração. Para mais informações sobre o modelo de lançamento do Bazel, consulte a página Modelo de lançamento.
Resumo
- É recomendável usar sinalizações
--incompatible_*para alterações interruptivas. - Para cada sinalização
--incompatible_*, um problema do GitHub explica a mudança de comportamento e tem como objetivo fornecer um roteiro de migração. - É recomendável fazer o backport das flags incompatíveis para a versão mais recente do LTS sem ativá-las por padrão.
- As APIs e o comportamento protegidos por uma sinalização
--experimental_*podem mudar a qualquer momento. - Nunca execute builds de produção com as sinalizações
--experimental_*ou--incompatible_*.
Como seguir essa política
- Para usuários do Bazel: como atualizar o Bazel
- Para colaboradores: práticas recomendadas para mudanças incompatíveis
- Para gerentes de lançamento: como atualizar os marcadores de problemas e fazer a versão
O que é uma funcionalidade estável?
Em geral, APIs ou comportamentos sem sinalizações --experimental_... são considerados
recursos estáveis e compatíveis no Bazel.
Isso inclui:
- Linguagem e APIs Starlark
- Regras incluídas no Bazel
- APIs do Bazel, como APIs de execução remota ou protocolo de evento de build
- Sinalizações e a semântica delas
Mudanças incompatíveis e roteiros de migração
Para cada mudança incompatível em uma nova versão, a equipe do Bazel visa fornecer um
roteiro de migração que ajuda a atualizar seu código (arquivos BUILD e .bzl, bem como
qualquer uso do Bazel em scripts, da API Bazel e assim por diante).
As alterações incompatíveis precisam ter uma sinalização --incompatible_* associada e um
problema correspondente do GitHub.
É recomendável fazer o backport da flag incompatível e das mudanças relevantes para a versão mais recente do LTS sem ativar a flag por padrão. Isso permite que os usuários migrem para as alterações incompatíveis antes que a próxima versão do LTS fique disponível.
Informar alterações incompatíveis
A principal fonte de informações sobre alterações incompatíveis são os problemas do GitHub marcados com um rótulo"incompatible-change".
Para cada alteração incompatível, o problema especifica o seguinte:
- Nome da sinalização que controla a alteração incompatível
- Descrição da funcionalidade alterada
- Receita de migração
Quando uma alteração incompatível estiver pronta para migração com o Bazel no HEAD
(portanto, também na próxima versão contínua do Bazel), ela precisa ser marcada com
o rótulo migration-ready. O problema de alteração incompatível é encerrado quando a sinalização incompatível é movida para "HEAD".