Esta página oferece 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. Novo LTS principal 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 flags
--incompatible_*para mudanças de interrupção. - Para cada flag
--incompatible_*, um problema do GitHub explica a mudança no comportamento e tem como objetivo fornecer uma receita de migração. - É recomendável que as flags incompatíveis sejamportadas de volta para a versão LTS mais recente sem ativar a flag por padrão.
- As APIs e o comportamento protegido por uma flag
--experimental_*podem mudar a qualquer momento. - Nunca execute builds de produção com as flags
--experimental_*ou--incompatible_*.
Como obedecer a essa 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 é funcionalidade estável?
Em geral, APIs ou comportamentos sem flags --experimental_... são considerados
recursos estáveis 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 semântica
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 uma
receita de migração que ajude você a atualizar seu código (arquivos BUILD e .bzl, bem
como qualquer uso do Bazel em scripts, uso da API do Bazel e assim por diante).
As mudanças incompatíveis precisam ter uma flag --incompatible_* associada e um
problema correspondente no GitHub.
É recomendável fazer a retrocompatibilidade da flag incompatível e das alterações relevantes para a versão mais recente do LTS sem ativar a flag por padrão. Isso permite que os usuários migrar para as mudanças incompatíveis antes que a próxima versão do LTS seja disponíveis.
Como comunicar mudanças incompatíveis
A principal fonte de informações sobre mudanças incompatíveis são problemas do GitHub marcado com "incompatível-alteração" rótulo.
Para cada mudança incompatível, o problema especifica o seguinte:
- Nome da flag que controla a mudança incompatível
- Descrição da funcionalidade alterada
- Receita de migração
Quando uma mudança incompatível estiver pronta para migração com o Bazel em HEAD
(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
flag incompatível seja invertida em HEAD.