Guia para lançar alterações interruptivas

É inevitável que façamos mudanças interruptivas no Bazel. Precisaremos mudar nossos designs e corrigir o que não funciona muito bem. No entanto, precisamos garantir que a comunidade e o ecossistema do Bazel possam acompanhar. Para isso, o projeto do Bazel adotou uma política de compatibilidade com versões anteriores. Este documento descreve o processo para que os colaboradores do Bazel façam uma mudança interruptiva no Bazel para aderir a essa política.

1. Siga a política do documento de design.

2. Registre um problema no GitHub.

3. Implemente a mudança.

4. Atualize os rótulos

5. Inverta a flag incompatível.

Problema do GitHub

Registre um problema no GitHub no repositório do Bazel. Consulte o exemplo.

Recomendamos que:

• O título comece com o nome da flag (que começa com incompatible_).

• Você adicione o rótulo incompatible-change.

• A descrição contenha uma descrição da mudança e um link para documentos de design relevantes.

• A descrição contenha uma receita de migração para explicar aos usuários como eles devem atualizar o código. O ideal é que, quando a mudança for mecânica, inclua um link para uma ferramenta de migração.

• A descrição inclua um exemplo da mensagem de erro que os usuários vão receber se não migrarem. Isso vai tornar o problema do GitHub mais detectável nos mecanismos de pesquisa. Verifique se a mensagem de erro é útil e acionável. Quando possível, a mensagem de erro precisa incluir o nome da flag incompatível.

Para a ferramenta de migração, considere contribuir com o Buildifier. Ele pode aplicar correções automatizadas a arquivos BUILD, WORKSPACE e .bzl. Ele também pode informar avisos.

Implementação

Crie uma nova flag no Bazel. O valor padrão precisa ser "false". O texto de ajuda precisa conter o URL do problema do GitHub. Como o nome da flag começa com incompatible_, ela precisa de tags de metadados:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Na descrição da confirmação, adicione um breve resumo da flag. Adicione também RELNOTES: no seguinte formato: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

A confirmação também precisa atualizar a documentação relevante para que não haja uma janela de confirmações em que o código seja inconsistente com os documentos. Como nossa documentação é versionada, as mudanças nos documentos não serão lançadas prematuramente.

Rótulos

Depois que a confirmação for mesclada e a mudança incompatível estiver pronta para ser adotada, adicione o rótulo migration-ready ao problema do GitHub.

Se um problema for encontrado com a flag e os usuários ainda não precisarem migrar, remova as flags migration-ready.

Se você planeja inverter a flag na próxima versão principal, adicione o rótulo `breaking-change-X.0" ao problema.

atualização de repositórios.

O Bazel CI testa uma lista de projetos importantes em Bazel@HEAD + Downstream. A maioria deles costuma ser dependências de outros projetos do Bazel. Portanto, é importante migrá-los para desbloquear a migração para a comunidade mais ampla.

Para monitorar o status da migração desses projetos, use o bazelisk-plus-incompatible-flags pipeline, confira como esse pipeline funciona aqui.

A migração de projetos no pipeline downstream NÃO é totalmente de responsabilidade do autor da mudança incompatível. No entanto, você pode fazer o seguinte para acelerar a migração e facilitar a vida dos usuários do Bazel e da equipe verde do Bazel.

1. Registre problemas no GitHub para notificar os proprietários dos projetos downstream interrompidos pela mudança incompatível.
2. Envie solicitações de envio para corrigir projetos downstream.
3. Entre em contato com a comunidade do Bazel para receber ajuda na migração (por exemplo, o SIG de autores de regras do Bazel).

Inverter a flag

Antes de inverter o valor padrão da flag para "true", verifique se:

• Os repositórios principais do ecossistema foram migrados.

  No bazelisk-plus-incompatible-flags pipeline, a flag precisa aparecer em The following flags didn't break any passing Bazel team owned/co-owned projects.

• As preocupações e perguntas do usuário foram resolvidas.

Quando a flag estiver pronta para ser invertida no Bazel, mas bloqueada na migração interna no Google, considere definir o valor da flag como "false" no arquivo blazerc interno para desbloquear a inversão da flag. Ao fazer isso, podemos garantir que os usuários do Bazel dependam do novo comportamento por padrão o mais cedo possível.

Ao mudar o padrão da flag para "true", faça o seguinte:

• Use RELNOTES[INC] na descrição da confirmação, com o seguinte formato: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details Você pode incluir mais informações no restante da descrição da confirmação.
• Use Fixes #xyz na descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.
• Revise e atualize a documentação, se necessário.
• Registre um novo problema #abc para acompanhar a remoção da flag.

Remover a flag

Depois que a flag for invertida no HEAD, ela precisará ser removida do Bazel. Quando você planeja remover a flag incompatível:

• Considere deixar mais tempo para os usuários migrarem se for uma mudança incompatível importante. O ideal é que a flag esteja disponível em pelo menos uma versão principal.
• Para a confirmação que remove a flag, use Fixes #abc na descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.