Guia para lançar alterações interruptivas

É inevitável que façamos mudanças interruptivas no Bazel. Vamos precisar mudar nossos designs e corrigir o que não está funcionando 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 os colaboradores do Bazel fazerem uma mudança destrutiva no Bazel para aderir a essa política.

1. Siga a política de documentos de design.

2. Registre um problema no GitHub.

3. Implemente a mudança.

4. Atualize os rótulos.

5. Atualize os repositórios.

6. Inverta a flag incompatível.

Problema no GitHub

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

Recomendamos que:

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

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

• A descrição contém uma descrição da mudança e um link para os documentos de design relevantes.

• A descrição contém uma receita de migração para explicar aos usuários como 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 inclui um exemplo da mensagem de erro que os usuários vão receber se não fizerem a migração. Isso vai facilitar a descoberta do problema no GitHub pelos mecanismos de pesquisa. Verifique se a mensagem de erro é útil e decisiva. Quando possível, a mensagem de erro deve incluir o nome da flag incompatível.

Para a ferramenta de migração, considere contribuir com o Buildifier. Ele pode aplicar correções automáticas 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 no GitHub. Como o nome da flag começa com incompatible_, ele precisa de tags de metadados:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Na descrição do commit, 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

O commit também precisa atualizar a documentação relevante para que não haja uma janela de commits em que o código seja inconsistente com os documentos. Como nossa documentação tem controle de versão, as mudanças não serão lançadas prematuramente por engano.

Rótulos

Quando o commit for mesclado 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 geralmente são dependências de outros projetos do Bazel. Por isso, é importante migrá-los para desbloquear a migração para a comunidade em geral. Para monitorar o status da migração desses projetos, use o pipeline bazelisk-plus-incompatible-flags. Confira como esse pipeline funciona aqui.

Nossa equipe de suporte a desenvolvedores monitora o rótulo migration-ready. Depois que você adicionar esse rótulo ao problema do GitHub, ele vai processar o seguinte:

1. Crie um comentário no problema do GitHub para acompanhar a lista de falhas e projetos downstream que precisam ser migrados (confira o exemplo).

2. Abra problemas no GitHub para notificar os proprietários de todos os projetos downstream afetados pela mudança incompatível (confira um exemplo).

3. Faça acompanhamento para garantir que todos os problemas sejam resolvidos antes da data de lançamento

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

1. Envie PRs para corrigir projetos downstream.

2. Entre em contato com a comunidade do Bazel para receber ajuda na migração (por exemplo, Bazel Rules Authors SIG).

Inverter a flag

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

• Os repositórios principais do ecossistema são migrados.

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

• Todos os problemas na lista de verificação estão marcados como corrigidos/resolvidos.

• As dúvidas e preocupações dos usuários 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. Assim, garantimos que os usuários do Bazel dependam do novo comportamento por padrão o mais rápido possível.

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

• Use RELNOTES[INC] na descrição do commit, 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 do commit.
• Use Fixes #xyz na descrição para que o problema do GitHub seja fechado quando o commit for mesclado.
• 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 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.