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 e é 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 LTS mais recentes do Bazel.
Enquanto isso, a própria regra pode enviar alterações incompatíveis para seus usuários conforme muito bem. Quando combinadas com mudanças de interrupção 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. Uma migração gerenciável é definido como um processo em que os usuários não são forçados a atualizar o simultaneamente a versão principal da regra e a do Bazel. permitindo que os usuários lidem com alterações incompatíveis de uma fonte por vez.
Por exemplo, com a seguinte matriz de compatibilidade:
- Migrar de regras_foo 1.x + Bazel 4.x para regras_foo 2.x + Bazel 5.x não é gerenciável, pois os usuários precisam fazer upgrade da versão principal regras_foo e 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.
| 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 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 do 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 deve seguir Semântica Controle de versão: versões secundárias do mesmo 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 Bazel em HEAD. Para isso,
é possível
- Configurar seus próprios testes de CI com o Bazel no HEAD
- Adicione seu projeto ao Bazel downstream testing; a equipe do Bazel registra problemas no seu projeto se houver alterações interruptivas nele. afetar seu projeto, e você deve seguir nosso projeto downstream políticas resolver problemas rapidamente.
- A versão principal mais recente da regra precisa ser compatível com a versão mais recente Versão LTS do Bazel.
- 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.
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 versão LTS do Bazel, os autores de regras podem:
- Solicitar que recursos compatíveis com versões anteriores sejam transferidos para 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, é possível migrar as regras para O Bazel é incompatível com mudanças e os novos recursos dele são usados no HEAD sem que sejam usados. descartando a compatibilidade com a versão mais recente do LTS do Bazel.