Guia para lançar alterações interruptivas

Informar um problema Mostrar fonte Por noite · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

É inevitável fazer mudanças interruptivas no Bazel. Teremos que alterar nossos designs e corrigir as coisas que não funcionam muito bem. No entanto, precisamos para garantir que o ecossistema da comunidade e do Bazel acompanhe esse processo. 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 interrupção mudança 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 no GitHub (em inglês) 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ç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 documentos de design.

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

  • A descrição inclui um exemplo da mensagem de erro que os usuários receberão se mas não migram. Isso tornará o problema do GitHub mais detectável mecanismos de pesquisa. Verifique se a mensagem de erro é útil e acionável. Quando possível, a mensagem de erro deve incluir o nome do elemento incompatível .

Na ferramenta de migração, considere contribuir para 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 deve conter o URL do problema no GitHub. Como o nome da sinalização 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 Janela de commits em que o código é inconsistente com os documentos. Como nossos documentação com controle de versão, as alterações nos documentos não serão aplicadas inadvertidamente lançado prematuramente.

Rótulos

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

Se um problema for encontrado com a sinalização e os usuários não precisarem migrar ainda: remova as sinalizações migration-ready.

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

atualização de repositórios.

A CI do Bazel testa uma lista de projetos importantes em Bazel@HEAD + Downstream A maioria deles é frequentemente 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 esse pipeline 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 vai 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. Ao fazer isso, 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 formato: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details É possível 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 encerrado quando o commit for mesclado.
  • 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.
  • Para o commit que remove a flag, use Fixes #abc na descrição. para que o problema no GitHub seja encerrado quando a confirmação for mesclada.