Guia para lançar alterações interruptivas

Informar um problema Acessar código-fonte

É inevitável fazer mudanças interruptivas no Bazel. Teremos que mudar nossos designs e corrigir as coisas que não funcionam bem. No entanto, precisamos garantir que o ecossistema da comunidade e do Bazel possa acompanhar. Por 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 alteração interruptiva no Bazel para aderir a essa política.

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

  2. Registre um problema no GitHub (link em inglês).

  3. Implementar a mudança.

  4. Atualizar marcadores

  5. Inverta a sinalização incompatível.

Problema no GitHub

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

Recomendamos o seguinte:

  • O título começa com o nome da sinalização (o nome da sinalização começará com incompatible_).

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

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

  • A descrição contém um roteiro 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 receberão se não migrarem. Isso 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 sinalização incompatível.

Para a ferramenta de migração, contribua com o Buildifier. Ele aplica correções automáticas a arquivos BUILD, WORKSPACE e .bzl. Além disso, ela pode informar avisos.

Implementação

Crie uma nova flag no Bazel. O valor padrão precisa ser falso. O texto de ajuda precisa conter o URL do problema no GitHub. Como o nome da sinalização começa com incompatible_, ela 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

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 tem controle de versões, as mudanças não serão lançadas prematuramente por acidente.

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 sinalização e os usuários ainda não precisarem migrar: remova as sinalizações migration-ready.

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

atualização de repositórios.

A CI do Bazel testa uma lista de projetos importantes em Bazel@HEAD + Downstream. A maioria deles costuma ser dependências de outros projetos do Bazel. Por isso, é importante migrá-los para possibilitar 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 aqui como ele funciona.

A migração de projetos no pipeline downstream NÃO é inteiramente 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 Team.

  1. Registre problemas no GitHub para notificar os proprietários dos projetos downstream corrompidos pela alteração incompatível.
  2. Envie PRs para corrigir projetos downstream.
  3. Entre em contato com a comunidade do Bazel para receber ajuda na migração (por exemplo, Bazel Rules Authors SIG).

Invertendo a bandeira

Antes de alterar 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 sinalização deve aparecer em The following flags didn't break any passing Bazel team owned/co-owned projects.

  • As preocupações e dúvidas dos usuários foram resolvidas.

Quando a flag estiver pronta para ser ativada no Bazel, mas for bloqueada na migração interna no Google, defina o valor dela como "false" no arquivo blazerc interno para desbloqueá-la. Assim, os usuários do Bazel precisam depender do novo comportamento por padrão o mais cedo possível.

Ao alterar o padrão de sinalização para verdadeiro:

  • 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 a confirmação for mesclada.
  • Revise e atualize a documentação, se necessário.
  • Registre um novo problema #abc para rastrear a remoção da sinalização.

Como remover a sinalização

Depois que a flag é invertida em HEAD, ela precisa ser removida do Bazel. Quando você planeja remover a flag incompatível:

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