As regras do Bazel Starlark podem interromper a compatibilidade com as versões LTS do Bazel nos dois cenários a seguir:
- A regra quebra a compatibilidade com versões futuras de LTS porque um recurso de que ela depende é removido do Bazel em 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 nas versões mais recentes do LTS do Bazel.
Enquanto isso, a própria regra também pode enviar alterações incompatíveis para seus usuários. Quando combinado com alterações interruptivas no Bazel, o upgrade da versão da regra e da versão do Bazel pode ser uma fonte de frustração para os usuários do Bazel. Nesta página, os autores de regras precisam manter a compatibilidade com o Bazel para facilitar o upgrade do Bazel e das regras.
Processo de migração gerenciável
Embora não seja obviamente viá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 lidem com alterações 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, porque os usuários podem primeiro fazer upgrade do Rules_foo de 2.x para 3.x sem alterar 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 do LTS do Bazel.
✅: pelo menos uma versão da regra é compatível com a versão mais recente da versão do Bazel LTS.
Práticas recomendadas
Como autor de regras do Bazel, é possível 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ões semântico: versões secundárias da mesma versão principal são compatíveis com versões anteriores.
- A regra em HEAD precisa ser compatível com a versão mais recente do LTS do Bazel.
- A regra em HEAD precisa ser compatível com o Bazel em HEAD. Para isso,
você pode
- Configure seus próprios testes de CI com o Bazel em HEAD
- Adicione o projeto ao teste downstream do Bazel (link em inglês). A equipe do Bazel vai registrar problemas no projeto se as alterações interruptivas afetarem o 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 LTS do Bazel compatível com a versão principal anterior da regra.
Alcançar 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 em HEAD e a versão mais recente do Bazel LTS, os autores de regras podem:
- Solicite a retrocompatibilidade de recursos compatíveis com versões anteriores para a versão mais recente do LTS. 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 ser capazes de migrar para mudanças incompatíveis com o Bazel e usar os novos recursos dele no HEAD sem cancelar a compatibilidade com a versão mais recente do LTS do Bazel.