As regras do Bazel Starlark podem interromper a compatibilidade com as versões do Bazel LTS nos dois cenários a seguir:
- A regra quebra a compatibilidade com versões futuras do LTS porque um recurso de que depende depende de o Bazel em HEAD.
- A regra quebra a compatibilidade com as versões de LTS atuais ou mais antigas porque um recurso de que depende depende apenas de versões mais recentes do Bazel LTS.
Enquanto isso, a regra em si também pode enviar alterações incompatíveis para os usuários. Quando combinada com alterações interruptivas no Bazel, o upgrade da versão da regra e do Bazel pode ser uma fonte de frustração para os usuários do Bazel. Nesta página, explicamos como os autores de regras precisam manter a compatibilidade de regras com o Bazel para facilitar a atualização do Bazel e das regras.
Processo de migração gerenciável
Embora obviamente não seja viável garantir compatibilidade entre cada versão do Bazel e cada versão 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 origem 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 atualizar a versão principal de rules_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, porque os usuários podem primeiro fazer upgrade de rules_foo de 2.x para 3.x sem alterar a versão principal do Bazel e depois atualizar o Bazel de 5.x para 6.x.
| rules_foo 1.x | rules_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 da Bazel LTS.
Práticas recomendadas
Como autor do Bazel, você pode garantir um processo de migração gerenciável pelos 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 em HEAD deve ser compatível com a versão mais recente do Bazel LTS.
- A regra em HEAD deve ser compatível com Bazel em HEAD. Para isso, é possível
- Configure seu próprio teste de CI com o Bazel em HEAD
- Adicione seu projeto aos testes downstream do Bazel. A equipe do Bazel enviará os problemas ao seu projeto se as alterações interruptivas no Bazel afetarem seu projeto. Siga nossas políticas do projeto downstream para resolver 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 Bazel LTS compatível com a versão principal anterior da regra.
Atingir 2. e 3. é a tarefa mais importante, pois permite alcançar 4. e 5. naturalmente.
Para facilitar a compatibilidade com o Bazel no HEAD e na versão mais recente do Bazel LTS, os autores das regras podem:
- Solicite que recursos retrocompatíveis sejam compatíveis com 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 precisam ser capazes de migrar para alterações incompatíveis com o Bazel e usar novos recursos do Bazel em HEAD sem deixar de ser compatível com a versão mais recente do Bazel LTS.