As regras do Bazel Starlark podem interromper a compatibilidade com as versões LTS do Bazel nos seguintes dois cenários:
- A regra quebra a compatibilidade com versões LTS futuras porque um recurso depende dele, que é removido do Bazel no HEAD.
- A regra quebra a compatibilidade com as versões LTS atuais ou mais antigas porque um recurso em que ela depende está disponível apenas nas versões mais recentes do Bazel LTS.
Enquanto isso, a própria regra também pode enviar mudanças incompatíveis para os usuários. Quando combinadas com mudanças importantes no Bazel, a atualização da versão da regra e do Bazel pode ser uma fonte de frustração para os usuários do Bazel. Esta página aborda como os autores de regras devem manter a compatibilidade com o Bazel para facilitar o upgrade do Bazel e das regras.
Processo de migração gerenciável
Obviamente, não é viável garantir a compatibilidade entre todas as versões do Bazel e da regra, mas nosso objetivo é garantir que o processo de migração continue gerenciável para os usuários do Bazel. Um processo de migração gerenciável é definido como um processo em que os usuários não são forçados a atualizar a versão principal da regra e a versão principal do Bazel simultaneamente, permitindo que os usuários processem mudanças incompatíveis de uma fonte por vez.
Por exemplo, com a seguinte matriz de compatibilidade:
- A migração de rules_foo 1.x + Bazel 4.x para rules_foo 2.x + Bazel 5.x não é considerada gerenciável, porque os usuários precisam fazer upgrade da versão principal de rules_foo e do Bazel ao mesmo tempo.
- A migração de rules_foo 2.x + Bazel 5.x para rules_foo 3.x + Bazel 6.x é considerada gerenciável, já que os usuários podem primeiro fazer upgrade de rules_foo 2.x para 3.x sem mudar a versão principal do Bazel e depois fazer upgrade do Bazel 5.x para 6.x.
| rules_foo 1.x | rules_foo 2.x | rules_foo 3.x | HEAD | |
|---|---|---|---|---|
| Bazel 4.x | ✅ | ❌ | ❌ | ❌ |
| Bazel 5.x | ❌ | ✅ | ✅ | ❌ |
| Bazel 6.x | ❌ | ❌ | ✅ | ✅ |
| HEAD | ❌ | ❌ | ❌ | ✅ |
❌: nenhuma versão da regra principal é compatível com a versão do Bazel LTS.
✅: pelo menos uma versão da regra é compatível com a versão mais recente da versão LTS do Bazel.
Práticas recomendadas
Como autores de regras do Bazel, você pode garantir um processo de migração gerenciável para os usuários seguindo estas práticas recomendadas:
- A regra precisa seguir o controle de versão semântico: versões secundárias da mesma versão principal são compatíveis com versões anteriores.
- A regra no HEAD precisa ser compatível com a versão mais recente do Bazel LTS.
- A regra no HEAD precisa ser compatível com o Bazel no HEAD. Para isso,
- Configurar seus próprios testes de CI com o Bazel no HEAD
- Adicione seu projeto ao teste downstream do Bazel. A equipe do Bazel envia problemas para seu projeto se as alterações de ruptura no Bazel afetarem seu projeto. Você precisa seguir nossas políticas de projeto downstream para resolver os problemas em tempo hábil.
- A versão principal mais recente da regra precisa ser compatível com a versão mais recente do Bazel LTS.
- Uma nova versão principal da regra precisa ser compatível com a última versão do Bazel LTS com suporte da versão principal anterior da regra.
Conseguir 2. e 3. é a tarefa mais importante, porque permite alcançar 4. e 5. naturalmente.
Para facilitar a manutenção da compatibilidade com o Bazel no HEAD e a versão mais recente do Bazel LTS, os autores de regras podem:
- Solicite que recursos com compatibilidade com versões anteriores sejam transferidos para a versão LTS mais recente. Confira o processo de lançamento para mais detalhes.
- Use bazel_features para fazer a detecção de recursos do Bazel.
Em geral, com as abordagens recomendadas, as regras precisam migrar para mudanças incompatíveis do Bazel e usar novos recursos do Bazel no HEAD sem perder a compatibilidade com a versão mais recente do Bazel LTS.