Se você planeja adicionar, mudar 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 dele antes de enviar a mudança.
Confira alguns exemplos de mudanças significativas:
- Adição ou exclusão de regras de build nativas
- Mudanças 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, semântica ou APIs do Starlark
- Mudanças que podem ter um efeito generalizado na performance ou no uso de memória do Bazel (para melhor ou para pior)
- Mudanças em APIs internas amplamente usadas
- Mudanças em flags e na interface de linha de comando
Motivos para revisões de design
Ao escrever um documento de design, você pode se coordenar com outros desenvolvedores do Bazel e buscar orientação da equipe principal do Bazel. Por exemplo, quando uma proposta adiciona, remove ou modifica qualquer função ou objeto disponível nos arquivos BUILD, WORKSPACE ou bzl, adicione a equipe do Starlark como revisores. Os documentos de design são revisados 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 avaliadas não apenas quanto à viabilidade técnica, mas também quanto à importância em relação a outras solicitações de recursos.
- Os recursos do Bazel são implementados com frequência por pessoas de fora da equipe principal. Esses colaboradores têm níveis de experiência muito variados no Bazel.
- A própria equipe do Bazel tem níveis de experiência variados. Nenhum membro da equipe tem uma compreensão completa de todos os aspectos do Bazel.
- As mudanças no Bazel precisam considerar a compatibilidade com versões anteriores e evitar mudanças interruptivas.
A política de revisão de design do Bazel ajuda a maximizar a probabilidade de que:
- todas as solicitações de recursos recebam um nível básico de análise.
- as pessoas certas vão analisar os designs antes de investirmos em uma implementação que pode não funcionar.
Para começar, confira os documentos de design no repositório de propostas do Bazel. Os designs são trabalhos em andamento, então os detalhes de implementação podem mudar com o tempo e com o feedback. Os documentos de design publicados capturam o design inicial, e não as mudanças contínuas à medida que os designs são implementados. Sempre acesse a documentação para descrições da funcionalidade atual do Bazel.
Fluxo de trabalho do colaborador
Como colaborador, você pode escrever um documento de design, enviar solicitações de envio e pedir 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 mudança importante
- lista de revisores, incluindo um (e apenas um) revisor principal
- status atual (rascunho, em revisão, aprovado, rejeitado, em implementação, implementado)
- link para o tópico de discussão (a ser adicionado após o anúncio)
O documento pode ser escrito como um documento do Google acessível a todos ou usando o Markdown. Leia abaixo sobre uma comparação entre Markdown e 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 envio (PR, na sigla em inglês) para adicionar o documento ao índice de design. Adicione o arquivo Markdown ou um link de documento à sua solicitação de envio.
Quando possível, escolha um revisor principal. e envie uma cópia para outros revisores. Se você não escolher um revisor principal, um mantenedor do Bazel vai atribuir um à sua solicitação de envio.
Depois de criar a solicitação de envio, 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 a solicitação de envio quando eles acreditam que o processo de revisão pode começar. Isso não significa que a proposta seja perfeita ou que será aprovada. Significa que ela contém informações suficientes para iniciar a discussão.
Anunciar a nova proposta
Envie um anúncio para bazel-dev quando a solicitação de envio for enviada.
Você pode copiar outros grupos (por exemplo, bazel-discuss, para receber feedback dos usuários finais do Bazel).
Fazer iterações com revisores
Qualquer pessoa interessada pode comentar sua proposta. Tente responder a perguntas, esclarecer a proposta e abordar preocupações.
A discussão precisa acontecer no tópico do anúncio. Se a proposta estiver em um documento do Google, os comentários poderão ser usados (observação: comentários anônimos são permitidos).
Atualizar o status
Crie uma nova solicitação de envio para atualizar o status da proposta quando a iteração estiver concluída. Envie a solicitação de envio para o mesmo revisor principal e envie uma cópia para os outros revisores.
Para aceitar oficialmente a proposta, o revisor principal aprova a solicitação de envio depois de garantir que os outros revisores concordem com a decisão.
É necessário que haja 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 suas preocupações.
A implementação pode começar antes que a proposta seja aceita, por exemplo, como uma prova de conceito ou uma experimentação. No entanto, não é possível enviar a mudança antes que a revisão seja concluída.
Como escolher um revisor principal
Um revisor principal precisa ser um especialista no domínio que seja:
- Conhecedor dos subsistemas relevantes
- Objetivo e capaz de fornecer feedback construtivo
- Disponível durante todo o período de revisão para liderar o processo
Considere verificar os contatos de vários rótulos de equipe.
Markdown x Documentos Google
Decida o que funciona melhor para você, já que ambos são aceitos.
Benefícios de usar o Documentos Google:
- Eficaz para brainstorming, já que é fácil começar a usar.
- Edição colaborativa.
- Iteração rápida.
- Maneira fácil de sugerir edições.
Benefícios de usar arquivos Markdown:
- URLs limpos para vinculação.
- Registro explícito de revisões.
- Não é necessário configurar direitos de acesso antes de divulgar um link.
- Fácil de pesquisar com mecanismos de pesquisa.
- À prova de futuro: o texto simples não depende de nenhuma ferramenta específica e não exige 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 primeiro iterar em um documento do Google e depois convertê-lo para Markdown para posteridade.
Como usar o Documentos Google
Para consistência, use o modelo de documento de design do Bazel. Ele inclui o cabeçalho necessário e cria consistência visual com outros documentos relacionados ao Bazel. Para fazer isso, clique em Arquivo > Fazer uma cópia ou clique neste link para fazer uma cópia do documento de design modelo.
Para tornar o 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 poderá comentar anonimamente, mesmo sem uma Conta do Google.
Como usar Markdown
Os documentos são armazenados no GitHub e usam o estilo Markdown do GitHub (especificação).
Crie uma solicitação de envio para atualizar um documento existente. Mudanças significativas precisam ser revisadas pelos revisores de documentos. Mudanças triviais (como erros de digitação, 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, pedir mais informações, se necessário, e aprovar um design que passe pelo processo de revisão.
Quando você recebe uma nova proposta
- Dê uma olhada rápida no documento.
- Comente se faltarem informações importantes ou se o design não se adequar às metas do projeto.
- Sugira outros revisores.
- Aprove a solicitação de envio quando ela estiver pronta para revisão.
Durante o processo de revisão
- Participe de um diálogo com o autor do design sobre problemas ou que exigem esclarecimentos.
- Se apropriado, convide comentários de pessoas que não são revisores, mas que precisam estar cientes de o design.
- Decida quais comentários precisam ser abordados pelo autor como pré-requisito para aprovação.
- Escreva "LGTM" (Looks Good To Me) no tópico de discussão quando estiver satisfeito 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 principal
Você é responsável por tomar a decisão de implementação de um design pendente. Se você não puder fazer isso, identifique um delegado adequado (reatribua a solicitação de envio ao delegado) ou reatribua o bug a um gerente do Bazel para mais informações.
Durante o processo de revisão
- Garanta que o processo de iteração de comentários e design avance de forma construtiva.
- Antes da aprovação, verifique se as preocupações de outros revisores foram resolvidas.
Após a aprovação de todos os revisores
- Verifique se já passou pelo menos uma semana desde o anúncio na lista de e-mails.
- Verifique se a solicitação de envio atualiza o status.
- Aprove a solicitação de envio enviada pelo autor da proposta.
Rejeitar designs
- Verifique se o autor da solicitação de envio enviou uma solicitação de envio ou envie uma para ele.
- A solicitação de envio atualiza o status do documento.
- 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 suposições inválidas e reenviar").