Guia para lançar alterações interruptivas

Relatar um problema Conferir código-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. Atualize os marcadores.

  5. Atualizar repositórios.

  6. 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 ainda não precisarem migrar: 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. Veja aqui como esse pipeline funciona.

Nossa equipe de suporte ao desenvolvedor monitora o rótulo migration-ready. Depois que você adicionar esse rótulo ao problema do GitHub, ele lidará com o seguinte:

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

  2. Registre problemas no GitHub para notificar os proprietários de todos os projetos downstream corrompidos por uma mudança incompatível (veja o exemplo).

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

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

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.

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

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