As regras do Bazel Starlark podem quebrar a compatibilidade com as versões LTS do Bazel nos dois cenários a seguir:
- A regra quebra a compatibilidade com versões LTS futuras porque um recurso do qual ela depende é removido do Bazel no HEAD.
- A regra quebra a compatibilidade com as versões LTS atuais ou mais antigas porque um recurso do qual ela depende só está disponível em versões LTS mais recentes do Bazel.
Enquanto isso, a regra em si também pode enviar mudanças incompatíveis para os usuários bem. Quando combinada com mudanças importantes no Bazel, a atualização da versão da regra e da versão 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 de regras com o Bazel para facilitar a atualização do Bazel e das regras para os usuários.
Processo de migração gerenciável
Embora obviamente não seja possível garantir a compatibilidade entre todas as versões do Bazel e todas as versões da regra, nosso objetivo é garantir que o processo de migração permaneça 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 fazer upgrade da versão principal da regra e da 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, já que 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 de 2.x para 3.x sem mudar a versão principal do Bazel e, em seguida, fazer upgrade do Bazel de 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 versão principal da regra é compatível com a versão LTS do Bazel.
✅: 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: as 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 LTS mais recente do Bazel.
- A regra no HEAD precisa ser compatível com o Bazel no HEAD. Para isso,
você pode
- Configurar seus próprios testes de CI com o Bazel no HEAD
- Adicionar seu projeto aos testes downstream do Bazel ; a equipe do Bazel registra problemas no seu projeto se mudanças importantes no Bazel o afetarem, e você precisa seguir nossas políticas de projetos downstream para resolver problemas em tempo hábil.
- A versão principal mais recente da regra precisa ser compatível com a versão LTS mais recente do Bazel.
- Uma nova versão principal da regra precisa ser compatível com a última versão LTS do Bazel com suporte da versão principal anterior da regra.
A tarefa mais importante é alcançar 2 e 3, já que isso permite alcançar 4 e 5. naturalmente.
Para facilitar a manutenção da compatibilidade com o Bazel no HEAD e a versão LTS mais recente do Bazel, os autores de regras podem:
- Solicitar que recursos compatíveis com versões anteriores sejam transferidos para a versão LTS mais recente. Confira o processo de lançamento para mais detalhes.
- Usar bazel_features para fazer a detecção de recursos do Bazel.
Em geral, com as abordagens recomendadas, as regras precisam ser capazes de migrar para mudanças incompatíveis do Bazel e usar novos recursos do Bazel no HEAD sem perder a compatibilidade com a versão LTS mais recente do Bazel.