Guia para lançar alterações interruptivas

É inevitável que façamos mudanças interruptivas no Bazel. Precisamos 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 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 do GitHub

Registre um problema no GitHub no repositório do Bazel. Confira 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 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 deve 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_, ele 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 no 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.

Nossa equipe de suporte ao desenvolvedor monitora o migration-ready rótulo. Depois de adicionar esse rótulo ao problema do GitHub, eles vão 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. Registre problemas no GitHub para notificar os proprietários de cada projeto downstream interrompido pela mudança incompatível (confira o exemplo).

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

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 verde do Bazel.

1. Envie PRs para corrigir projetos downstream.

2. 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.

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

• 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 do Google, defina 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.