Guia para lançar alterações interruptivas

É inevitável fazer alterações interruptivas no Bazel. Teremos que mudar nossos designs e corrigir as coisas que não funcionam muito bem. No entanto, precisamos garantir que o ecossistema da comunidade e do Bazel possa acompanhar. Para isso, o projeto Bazel adotou uma política de compatibilidade com versões anteriores (link em inglês). Neste documento, descrevemos o processo para colaboradores do Bazel fazerem uma alteração interruptiva para aderir a essa política.

  1. Siga a política do documento de design.

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

  3. Implemente a mudança.

  4. Atualizar rótulos

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

Problema no GitHub

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

Recomendamos que:

  • O título começa com o nome da flag (o nome dela 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 relevantes.

  • A descrição contém um roteiro de migração para explicar aos usuários como eles precisam atualizar o código. O ideal é que a mudança seja 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 migrarem. Isso tornará o problema do GitHub mais detectável pelos mecanismos de pesquisa. Certifique-se de que a mensagem de erro seja útil e possa ser transformada em ações. 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. É possível aplicar correções automáticas aos arquivos BUILD, WORKSPACE e .bzl. Ela também pode enviar alertas.

Implementação

Crie uma nova sinalização no Bazel. O valor padrão precisa ser falso. O texto de ajuda precisa conter o URL do problema do GitHub. Como o nome da sinalização 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 sinalização. Adicione também RELNOTES: neste 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 janela de confirmações em que o código fique inconsistente com os documentos. Como nossa documentação é controlada por versões, as mudanças neles não serão lançadas de forma acidental antes da hora.

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 inverter a sinalização 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. Portanto, é importante migrá-los para liberar a migração para a comunidade como um todo.

Para monitorar o status de migração desses projetos, use o pipeline bazelisk-plus-incompatible-flags (em inglês) e verifique como ele funciona neste link.

A migração de projetos no pipeline downstream NÃO é totalmente 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. Registre problemas no GitHub para notificar os proprietários dos projetos downstream corrompidos pela mudança 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, SIG Authors de regras do Bazel.

Virar a bandeira

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 sinalização precisa 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 sinalização estiver pronta para ser ativada no Bazel, mas bloqueada na migração interna no Google, defina o valor da sinalização como "false" no arquivo blazerc interno para desbloquear a inversão da sinalização. Ao fazer isso, é possível garantir que os usuários do Bazel dependam do novo comportamento por padrão o quanto antes.

Ao alterar o padrão da flag para "true":

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

Como remover a sinalização

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

  • Se essa for uma mudança muito incompatível, considere a possibilidade de deixar mais tempo para os usuários fazerem a migração. O ideal é que a sinalização esteja disponível em pelo menos uma versão principal.
  • Para a confirmação que remove a sinalização, use Fixes #abc na descrição para que o problema do GitHub seja fechado quando a confirmação for mesclada.