As regras do Bazel Starlark podem interromper a compatibilidade com as versões LTS dele nos seguintes cenários:
- A regra quebra a compatibilidade com versões futuras do LTS porque um recurso de que depende é removido do Bazel em HEAD.
- A regra quebra a compatibilidade com a versão atual ou mais antiga do LTS 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 os 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, abordamos como os autores de regras precisam manter a compatibilidade das regras com o Bazel para facilitar o upgrade do Bazel e das regras para os usuários.
Processo de migração gerenciável
Embora não seja viável garantir a compatibilidade entre todas as versões do Bazel e da regra, 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 fazer upgrade da versão principal da regra e da versão principal do Bazel simultaneamente, permitindo que os usuários processem alterações incompatíveis de uma fonte por vez.
Por exemplo, com a seguinte matriz de compatibilidade:
- A migração de regras_foo 1.x + Bazel 4.x para regras_foo 2.x + Bazel 5.x não é considerável gerenciável, porque os usuários precisam fazer upgrade da versão principal do 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 é considerável, porque 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 depois atualizar do Bazel de 5.x para 6.x.
| regras_foo 1.x | regras_foo 2.x | regras_foo 3.x | HEAD | |
|---|---|---|---|---|
| Bazel 4.x | ✅ | ❌ | ❌ | ❌ |
| Bazel 5.x | ❌ | ✅ | ✅ | ❌ |
| Bazel 6.x | ❌ | ❌ | ✅ | ✅ |
| HEAD | ❌ | ❌ | ❌ | ✅ |
❌: Nenhuma versão da 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 Bazel LTS.
Práticas recomendadas
Os autores de regras do Bazel 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ões semântico: versões secundárias da mesma versão principal são compatíveis com versões anteriores.
- A regra em HEAD deve ser compatível com a versão mais recente do LTS do Bazel.
- A regra em HEAD deve ser compatível com o Bazel em HEAD. Para fazer isso,
você pode
- Configurar seus próprios testes de CI com o Bazel em HEAD
- Adicione o projeto ao teste downstream do Bazel. Os arquivos da equipe do Bazel vão causar problemas no projeto se alterações interruptivas afetarem o projeto, e você precisará 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 aceita pela versão principal anterior da regra.
Atingir 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 com a versão mais recente do LTS do Bazel, os autores de regras podem:
- Solicite recursos compatíveis com versões anteriores para backport para a versão mais recente do LTS. Confira o processo de lançamento para mais detalhes.
- Use bazel_features para detectar a detecção de recursos do Bazel.
Em geral, com as abordagens recomendadas, as regras podem ser migradas para mudanças incompatíveis com o Bazel e usar os novos recursos do Bazel em HEAD sem descartar a compatibilidade com a versão mais recente do LTS do Bazel.