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 futuras do LTS porque um recurso de que ela depende foi removido do Bazel no HEAD.
- A regra quebra a compatibilidade com as versões LTS atuais ou mais antigas porque um recurso de que ela depende só está disponível em versões LTS mais recentes do Bazel.
Enquanto isso, a própria regra pode enviar mudanças incompatíveis para os usuários. Quando combinada com mudanças incompatíveis 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 mostra como os autores de regras devem manter a compatibilidade com o Bazel para facilitar o upgrade do Bazel e das regras pelos usuários.
Processo de migração gerenciável
Embora não seja possível garantir a compatibilidade entre todas as versões do Bazel e 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 obrigados a fazer upgrade da versão principal da regra e da versão principal do Bazel simultaneamente, permitindo que os usuários lidem com mudanças incompatíveis de uma fonte por vez.
Por exemplo, com a seguinte matriz de compatibilidade:
- Migrar de rules_foo 1.x + Bazel 4.x para rules_foo 2.x + Bazel 5.x não é considerado 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 regra principal é compatível com a versão LTS do Bazel.
✅: pelo menos uma versão da regra é compatível com a versão mais recente do LTS do Bazel.
Práticas recomendadas
Como autores de regras do Bazel, vocês podem 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 LTS mais recente do Bazel.
- A regra no HEAD precisa ser compatível com o Bazel no HEAD. Para isso, você pode
- Configurar seu próprio teste de CI com o Bazel no HEAD
- Adicione seu projeto ao teste downstream do Bazel. A equipe do Bazel registra problemas no seu projeto se mudanças incompatíveis no Bazel o afetarem, e você precisa seguir nossas políticas de projetos downstream para resolver problemas a tempo.
- 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 compatível com a versão principal anterior da regra.
Atingir os objetivos 2 e 3 é a tarefa mais importante, já que permite alcançar os objetivos 4 e 5. naturalmente.
Para facilitar a compatibilidade com o Bazel no HEAD e a versão mais recente do LTS, os autores de regras podem:
- Solicite que recursos compatíveis com versões anteriores sejam portados 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 podem migrar para mudanças incompatíveis com o Bazel e usar novos recursos do Bazel no HEAD sem perder a compatibilidade com a versão LTS mais recente do Bazel.