Nesta página, você encontra 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 do 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 as sinalizações
--incompatible_*para alterações interruptivas. - Para cada flag
--incompatible_*, um problema do GitHub explica a mudança no comportamento e tem como objetivo fornecer um roteiro de migração. - É recomendável fazer a retrocompatibilidade de sinalizações incompatíveis para a versão mais recente do LTS sem ativá-las por padrão.
- As APIs e o comportamento protegidos por uma flag
--experimental_*podem mudar a qualquer momento. - Nunca execute builds de produção com sinalizações
--experimental_*ou--incompatible_*.
Como seguir esta política
- Para usuários do Bazel: como atualizar o Bazel
- Para colaboradores: práticas recomendadas para mudanças incompatíveis
- Para os administradores da versão: como atualizar os rótulos de problemas e a versão
O que é uma funcionalidade estável?
Em geral, APIs ou comportamentos sem flags --experimental_... são considerados
recursos estáveis e compatíveis com o Bazel.
Isso inclui:
- Linguagem e APIs Starlark
- Regras empacotadas com o Bazel
- APIs do Bazel, como as APIs Remote Execution ou o Build Event Protocol
- Flags 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 tem como objetivo fornecer um
roteiro de migração (link em inglês) que ajuda você 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 do GitHub correspondente.
A sinalização incompatível e as alterações relevantes são recomendadas para backport para a versão mais recente do LTS sem ativar a sinalização por padrão. Isso permite que os usuários migrem em busca de alterações incompatíveis antes que a próxima versão do LTS esteja disponível.
Comunicação de mudanças incompatíveis
A principal fonte de informações sobre alterações incompatíveis são problemas do GitHub marcados com um rótulo"incompatível-change" (em inglês).
Para cada alteração incompatível, o problema especifica o seguinte:
- Nome do flag que controla a alteração incompatível
- Descrição da funcionalidade alterada
- Roteiro de migração
Quando uma alteração incompatível estiver pronta para migração com o Bazel em HEAD
(e, portanto, também com a próxima versão gradual do Bazel), ela será marcada com
o rótulo migration-ready. O problema de alteração incompatível é encerrado quando a sinalização incompatível é invertida em HEAD.