Se você planeja adicionar, alterar ou remover um recurso voltado para o usuário ou fazer uma mudança arquitetônica significativa no Bazel, é necessário escrever um documento de design e analisá-lo antes de enviar a alteração.
Veja alguns exemplos de alterações 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 única 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 geral no desempenho do Bazel ou no uso de memória (para o bem ou para o mal).
- Mudanças em APIs internas amplamente utilizadas
- Mudanças nas sinalizações e na interface de linha de comando.
Motivos para revisões de design
Ao escrever um documento de design, você pode coordenar outros desenvolvedores do Bazel e buscar orientação da equipe principal dele. Por exemplo, quando uma proposta adicionar, remover ou modificar qualquer função ou objeto disponível nos arquivos BUILD, WORKSPACE ou bzl, adicione a equipe 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 pela importância em relação a 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 variados de experiência com ele.
- A equipe do Bazel tem vários níveis de experiência. Nenhum membro da equipe consegue entender completamente todos os aspectos dele.
- As mudanças no Bazel precisam considerar a compatibilidade com versões anteriores e evitar alterações interrompidas.
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 avaliar os designs antes de investirmos em uma implementação que pode não funcionar.
Para ajudar você a começar, veja os documentos de design no Repositório de propostas do Bazel. Os designs estão em desenvolvimento, então os detalhes da implementação podem mudar ao longo do tempo e com feedback. Os documentos de design publicados capturam o projeto inicial, e não as mudanças contínuas à medida que os designs são implementados. Sempre acesse a documentação para ver descrições das funcionalidades atuais do Bazel.
Fluxo de trabalho do colaborador
Como colaborador, você pode 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 apenas um) revisor principal
- status atual (rascunho, em análise, aprovado, rejeitado, sendo implementado, implementado);
- link para a conversa (adicionado após o anúncio)
O documento pode ser escrito como um Google Doc legível por todos ou usando o Markdown. Leia abaixo sobre uma comparação do Markdown com o Documentos Google.
As propostas que têm 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 seu arquivo de marcação ou um link de documento ao seu RP.
Quando possível, escolha um revisor líder e coloque outros revisores. Se você não escolher um revisor líder, um mantenedor do Bazel vai atribuir um ao seu PR.
Depois de criar seu PR, os revisores podem fazer comentários preliminares durante a revisão do código. Por exemplo, o revisor líder pode sugerir revisores adicionais ou apontar informações ausentes. O revisor líder aprova a RP quando acredita que o processo de revisão pode começar. Isso não significa que a proposta é perfeita ou será aprovada, mas que ela contém informações suficientes para iniciar a discussão.
Anunciar a nova proposta
Envie um anúncio para bazel-dev quando o RP for enviado.
Você pode copiar outros grupos, por exemplo, bazel-discuss, para receber feedback dos usuários finais do Bazel.
Iterar com os revisores
Qualquer pessoa interessada pode comentar sobre sua proposta. Tente responder às perguntas, esclarecer a proposta e abordar preocupações.
A discussão deve acontecer na conversa do anúncio. Se a proposta estiver em um documento Google, comentários poderão ser usados (comentários anônimos são permitidos).
Atualizar o status
Crie um novo PR para atualizar o status da proposta, quando a iteração for concluída. Envie o PR para o mesmo revisor principal e copie os outros revisores.
Para aceitar oficialmente a proposta, o revisor líder aprova o RP depois de garantir que os outros revisores concordam com a decisão.
Deve 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 preocupações.
A implementação pode começar antes da aceitação da proposta, por exemplo, como uma prova de conceito ou um experimento. No entanto, não é possível enviar a alteração antes que a análise seja concluída.
Como escolher um revisor de leads
Um revisor de leads deve ser um especialista no domínio que seja:
- 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 em busca 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 Google Docs:
- Eficaz para brainstorming, pois é fácil no início.
- Edição colaborativa.
- Iteração rápida.
- Uma maneira fácil de sugerir edições.
Benefícios do uso de arquivos Markdown:
- Limpar URLs para vinculação.
- Registro explícito de revisões.
- Não esqueça de configurar os direitos de acesso antes de divulgar um link.
- Facilmente pesquisável com mecanismos de pesquisa.
- Tecnologia moderna: o texto simples não depende de nenhuma ferramenta específica e não requer conexão com a Internet.
- É possível atualizá-los mesmo que o autor não esteja mais por perto.
- Eles podem ser processados automaticamente (atualização/detecção de links inativos, busca lista de autores etc.).
Você pode optar por iterar primeiro em um documento Google e depois convertê-lo em Markdown para o futuro.
Como usar o Google Docs
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 File > Make a copy ou clique neste link para fazer uma cópia do modelo de documento de design.
Para tornar seu documento legível, clique em Compartilhar > Avançado > Alterar... 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 a variação de Markdown do GitHub (especificação).
Crie um PR para atualizar um documento. Mudanças significativas precisam ser analisadas 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 é aprovado no processo de revisão.
Ao receber uma nova proposta
- Dê uma olhada no documento.
- Comente se faltarem informações críticas ou se o design não se encaixar com os objetivos do projeto.
- Sugira revisores adicionais.
- Aprove o PR quando ele estiver pronto para revisão.
Durante o processo de revisão
- Conversar com o autor do design sobre questões problemáticas ou que exigem esclarecimentos.
- Se apropriado, convide comentários de pessoas que não sejam revisores, que precisam conhecer o design.
- Decida quais comentários precisam ser abordados pelo autor como um pré-requisito da aprovação.
- Escreva "LGTM" (Looks Good To Me) na conversa 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 projetos que afetam o Bazel se eles não estiverem no índice de design.
Responsabilidades do revisor líder
Você é responsável por tomar a decisão de implementar um design pendente. Se não conseguir fazer isso, identifique um delegado adequado (reatribua o PR a ele) ou reatribua o bug a um gerente do Bazel para disposição posterior.
Durante o processo de revisão
- Garantir que o processo de iteração de comentários e design avance de maneira construtiva.
- Antes da aprovação, garanta que as preocupações de outros revisores foram resolvidas.
Após a aprovação de todos os revisores
- Confirme se já se passou pelo menos uma semana desde o anúncio na lista de e-mails.
- Verifique se o RP atualiza o status.
- Aprove o PR enviado pelo autor da proposta.
Rejeição de designs
- Certifique-se de que o autor da RP envie uma RP ou envie uma PR.
- O RP atualiza o status do documento.
- Adicione um comentário ao documento explicando por que o design não pode ser aprovado no estado atual e descrevendo as próximas etapas, se houver (como "revisar as suposições inválidas e reenviar").