Documentos de design

Informar um problema Mostrar fonte Por noite · 7,4 do Google. 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Se você planeja adicionar, alterar ou remover um recurso voltado ao usuário ou fazer uma mudança arquitetônica significativa no Bazel, é necessário escrever um documento de design e fazer a revisão antes de enviar a mudança.

Confira alguns exemplos de mudanças significativas:

  • Adição ou exclusão de regras de build nativas
  • Alterações interruptivas nas regras nativas
  • Mudanças na semântica de uma regra de build nativa que afetam o comportamento de mais de uma regra
  • Mudanças na API de definição de regras do Bazel
  • Mudanças nas APIs que o Bazel usa para se conectar a outros sistemas
  • Mudanças na linguagem, na semântica ou nas APIs Starlark
  • Mudanças que podem ter um efeito generalizado no desempenho ou no uso da memória do Bazel (para melhor ou para pior)
  • Mudanças em APIs internas amplamente usadas
  • Mudanças nas flags e na interface da linha de comando.

Motivos para revisões de design

Ao escrever um documento de design, você pode coordenar com outros desenvolvedores do Bazel e procure orientação da equipe principal dele. Por exemplo, quando uma proposta é adicionada, remove ou modifica qualquer função ou objeto disponível em BUILD, WORKSPACE ou bzl, adicione a equipe Starlark como revisores. Os documentos de design são analisados antes do envio porque:

  • O Bazel é um sistema muito complexo. Mudanças locais aparentemente inofensivas podem ter consequências globais significativas.
  • A equipe recebe muitas solicitações de recursos dos usuários. essas solicitações precisam ser são avaliadas não só pela viabilidade técnica, mas pela importância em relação outras solicitações de recursos.
  • Os recursos do Bazel são frequentemente implementados por pessoas de fora da equipe principal. Esses colaboradores têm níveis muito diferentes de experiência com o Bazel.
  • A equipe do Bazel tem níveis variados de experiência. Nenhum membro da equipe tem um entendimento completo de todos os recursos do Bazel.
  • As mudanças no Bazel precisam considerar a compatibilidade com versões anteriores e evitar mudanças quebradas.

A política de revisão de design do Bazel ajuda a maximizar a probabilidade de:

  • todas as solicitações de recursos recebem um nível de referência de análise.
  • as pessoas certas vão opinar sobre os designs antes de investirmos em uma implementação que pode não funcionar.

Para ajudar você a começar, confira os documentos de design na Repositório de propostas do Bazel. Os designs estão em fase de desenvolvimento, então os detalhes de implementação podem mudar com o tempo e com o feedback. Os documentos publicados do projeto capturam o projeto inicial, e não às mudanças contínuas à medida que os designs são implementados. Sempre acesse documentação para descrições das funcionalidades atuais do Bazel.

Fluxo de trabalho do colaborador

Como colaborador, é possível escrever um documento de design, enviar solicitações de envio e solicitar revisores para sua proposta.

Escrever o documento de design

Todos os documentos de design precisam ter um cabeçalho que inclua:

  • autor
  • data da última grande alteração
  • lista de revisores, incluindo um (e somente um) revisor de leads
  • status atual (rascunho, em revisão, aprovado, rejeitado, em implementação, implementado)
  • link para a conversa (adicionado após o anúncio)

O documento pode ser escrito como um Documento Google legível por todos ou usando Markdown. Leia abaixo sobre Comparação do Markdown / Documentos Google.

As propostas que têm um impacto visível para o usuário precisam ter uma seção que documente o impacto na compatibilidade com versões anteriores (e um plano de lançamento, se necessário).

Criar uma solicitação de envio

Compartilhe seu documento de design criando uma solicitação de pull (PR, na sigla em inglês) para adicionar o documento ao índice de design. Adicione seu arquivo Markdown ou um link de documento à sua solicitação de pull.

Quando possível, escolha um revisor principal. e copie os outros revisores. Se você não escolher um revisor líder, um Bazel o mantenedor atribuirá um ao seu RP.

Depois que você cria a PR, os revisores podem fazer comentários preliminares durante a revisão de código. Por exemplo, o revisor principal pode sugerir outros revisores ou apontar informações ausentes. O revisor principal aprova o PR quando acredita que o processo de revisão pode começar. Isso não significa que a proposta é perfeita ou serão aprovados. isso significa que ela contém informações suficientes para inicie a discussão.

Anunciar a nova proposta

Enviar um aviso para bazel-dev quando o PR é enviado.

Você pode copiar outros grupos (por exemplo, bazel-discuss (em inglês) para receber feedback dos usuários finais do Bazel).

Iterar com revisores

Qualquer pessoa interessada pode comentar sobre sua proposta. Tente responder a perguntas, esclarecer a proposta e resolver as dúvidas.

A discussão deve acontecer na linha de execução do anúncio. Se a proposta estiver em um Documentos Google, comentários podem ser usados no lugar (Observação: comentários anônimos são permitido).

Atualizar o status

Crie um novo PR para atualizar o status da proposta, quando a iteração for concluído. Envie o PR para o mesmo revisor líder e copie os outros revisores.

Para aceitar oficialmente a proposta, o revisor principal aprova a PR depois de garantir que os outros revisores concordam com a decisão.

É preciso haver pelo menos uma semana entre o primeiro anúncio e a aprovação de uma proposta. Isso garante que os usuários tenham tempo suficiente para ler o documento e compartilhar as dúvidas.

A implementação pode começar antes que a proposta seja aceita, por exemplo, como prova de conceito ou experimentação. No entanto, não é possível enviar a alteração antes que a revisão seja concluída.

Como escolher um revisor principal

Um revisor principal precisa ser um especialista em domínio que:

  • Conhecer os subsistemas relevantes.
  • Objetivos e capazes de fornecer feedback construtivo
  • Disponível durante todo o período de revisão para liderar o processo

Verifique os contatos de várias equipes rótulos.

Markdown x Documentos Google

Decida qual funciona melhor para você, já que ambos são aceitos.

Benefícios de usar o Google Docs:

  • É eficaz para a discussão de ideias, já que é fácil de usar.
  • Edição colaborativa.
  • Iteração rápida.
  • Uma maneira fácil de sugerir edições.

Benefícios de usar arquivos Markdown:

  • Limpe os URLs para vincular.
  • Registro explícito de revisões.
  • Não se esqueça de configurar os direitos de acesso antes de divulgar um link.
  • Facilmente pesquisável com mecanismos de pesquisa.
  • Compatível com o futuro: o texto simples não está à mercê de nenhuma ferramenta específica e não requer uma conexão de Internet.
  • É possível atualizá-los mesmo que o autor não esteja mais por perto.
  • Eles podem ser processados automaticamente (atualizar/detectar links inativos, buscar lista de autores etc.).

Você pode optar por iterar em um documento Google e depois convertê-lo em Markdown para posteridade.

Como usar o Google Docs

Para manter a consistência, use o modelo de documento de design do Bazel. Ele inclui o cabeçalho necessário e cria recursos consistência com outros documentos relacionados ao Bazel. Para fazer isso, clique em Arquivo > Faça uma cópia ou clique neste link para fazer uma cópia do documento de design modelo.

Para tornar seu documento legível para o mundo, clique em Compartilhar > Avançado > Mudar… e escolha "Ativado: qualquer pessoa com o link". Se você permitir comentários no documento, qualquer pessoa pode comentar anonimamente, mesmo sem uma Conta do Google.

Como usar Markdown

Os documentos são armazenados no GitHub e usam o Markdown do GitHub (especificação).

Crie um PR para atualizar um documento. Mudanças significativas devem ser e revisado pelos revisores de documentos. Mudanças triviais (como erros de digitação e formatação) podem ser aprovadas por qualquer pessoa.

Fluxo de trabalho do revisor

Um revisor comenta, analisa e aprova documentos de design.

Responsabilidades gerais do revisor

Você é responsável por revisar documentos de design, solicitar mais informações, se necessário, e aprovar um design que passe pelo processo de revisão.

Quando você receber uma nova proposta

  1. Analise rapidamente o documento.
  2. Comente se faltarem informações críticas ou se o design não se encaixar com as metas do projeto.
  3. Sugerir outros revisores.
  4. Aprove o PR quando ele estiver pronto para revisão.

Durante o processo de revisão

  1. Participar de um diálogo com o autor do design sobre questões que são problemáticas ou precise de esclarecimentos.
  2. Se apropriado, convide comentários de pessoas que não são revisores e que precisam conhecer o design.
  3. Decidir quais comentários devem ser abordados pelo autor como um pré-requisito para aprovação.
  4. Escrever "LGTM" (Tudo certo para mim) na conversa quando você estiver satisfeitas com o estado atual da proposta.

Siga esse processo para todas as solicitações de revisão de design. Não aprove designs que afetem o Bazel se eles não estiverem no índice de design.

Responsabilidades do revisor líder

Você é responsável por decidir sobre a implementação. de um design pendente. Se não puder fazer isso, você deve identificar um um delegado adequado (reatribua o RP a ele) ou reatribua o bug a um Gerenciador do Bazel para disposição posterior.

Durante o processo de revisão

  1. Garantir que o processo de iteração de comentários e design avance de forma construtiva.
  2. Antes da aprovação, garanta que as preocupações dos outros revisores foram resolvido.

Após a aprovação de todos os revisores

  1. Verifique se já se passaram pelo menos uma semana desde o anúncio na lista de e-mails.
  2. Verifique se o RP atualiza o status.
  3. Aprovar a RP enviada pelo autor da proposta.

Como rejeitar designs

  1. Garantir que o autor da RP envia uma RP; ou enviar um RP.
  2. O RP atualiza o status do documento.
  3. Adicione um comentário ao documento explicando por que o design não pode ser aprovado em seu estado atual e descrevendo as próximas etapas, se houver (como "revisitar inválido suposições e reenviá-lo").