Se você planeja adicionar, mudar ou remover um recurso voltado para o usuário ou fazer uma mudança de arquitetura significativa no Bazel, é necessário gravar um documento de design e analisá-lo antes de enviar a mudança.
Veja 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 ú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 generalizado no desempenho ou no uso de memória do Bazel (para o bem ou para o mal)
- Mudanças nas APIs internas amplamente utilizadas.
- Mudanças nas flags e na interface de linha de comando.
Motivos para revisões de design
Ao escrever um documento de design, é possível coordenar com outros desenvolvedores do Bazel e buscar orientação da equipe principal do Bazel. 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 do Starlark como revisores. Os documentos de design são revisados antes do envio porque:
- O Bazel é um sistema muito complexo. Alterações 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 a importância em relação a outras solicitações de recursos.
- Os recursos do Bazel costumam ser implementados por pessoas de fora da equipe principal. Esses colaboradores têm níveis muito variados de experiência no Bazel.
- A equipe do Bazel tem vários níveis de conhecimento. Nenhum membro da equipe tem uma compreensão completa de todos os detalhes.
- As mudanças no Bazel precisam considerar a compatibilidade com versões anteriores e evitar alterações interruptivas.
A política de revisão de design do Bazel ajuda a maximizar a probabilidade de que:
- todas as solicitações de recursos recebem um nível básico de investigação.
- 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, consulte os documentos de design no repositório de propostas do Bazel (link em inglês). Os designs estão em fase de desenvolvimento, então os detalhes da implementação podem mudar ao longo do tempo e com feedback. Os documentos publicados capturam o projeto inicial, e não as mudanças em andamento à 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:
- author (autor)
- data da última grande alteração
- lista de revisores, incluindo um (e apenas um) revisor líder
- Status atual (rascunho, em análise, aprovado, rejeitado, em andamento, implementado)
- link para a conversa (a ser adicionado após o anúncio)
O documento pode ser redigido como um documento Google legível ou usando Markdown. Leia abaixo sobre uma comparação de Markdown / Documentos Google.
As propostas que têm um impacto visível ao usuário precisam ter uma seção documentando 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 PR.
Quando possível, escolha um revisor líder e coloque outros revisores em cópia. 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 outros revisores ou apontar informações ausentes. O revisor líder aprova o PR quando acredita que o processo de revisão pode começar. Isso não significa que a proposta é perfeita ou que 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 PR for enviado.
É possível copiar outros grupos (por exemplo, bazel-discuss) para receber feedback dos usuários finais do Bazel.
Iterar com revisores
Qualquer pessoa interessada pode comentar sua proposta. Tente responder a perguntas, esclarecer a proposta e abordar preocupações.
A discussão deve acontecer na conversa de anúncio. Se a proposta estiver em um arquivo do Documentos Google, é possível usar comentários. 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 líder e coloque os outros revisores em cópia.
Para aceitar oficialmente a proposta, o revisor líder aprova o PR após garantir que os outros revisores concordam com a decisão.
É preciso que haja pelo menos uma semana entre o primeiro anúncio e a aprovação da 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 alteração antes que a revisão seja concluída.
Como escolher um revisor de lead
Um revisor líder deve ser um especialista no domínio que tenha:
- Conhecer os subsistemas relevantes.
- Objetivo e capaz de fornecer feedback construtivo.
- Disponível durante todo o período de revisão para liderar o processo
Verifique se há vários rótulos de equipe nos contatos.
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 o brainstorm, já que é fácil começar.
- Edição colaborativa.
- Iteração rápida.
- Uma 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 se esqueça de configurar os direitos de acesso antes de divulgar um link.
- É fácil pesquisar 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á-las mesmo que o autor não esteja mais por perto.
- Eles podem ser processados automaticamente (atualizar/detectar links inativos, buscar lista de autores etc.).
É possível iterar primeiro em um documento Google e depois convertê-lo para Markdown para o futuro.
Como usar o Documentos Google
Para manter a consistência, use o modelo de documento de design do Bazel. Ela 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 neste link para fazer uma cópia do modelo de documento de design.
Para tornar o documento legível para todos, 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 existente. As mudanças significativas precisam ser analisadas 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, pedir informações adicionais, se necessário, e aprovar um design que passa no processo de revisão.
Quando você receber uma nova proposta
- Dê uma olhada rápida no documento.
- Comente se houver informações críticas ausentes ou se o design não se encaixa nas metas do projeto.
- Sugerir mais revisores.
- Aprove o PR quando ele estiver pronto para análise.
Durante o processo de revisão
- Converse com o autor do design sobre problemas problemáticos ou que precisam de esclarecimento.
- Se apropriado, convide comentários de não revisores que devem estar cientes do design.
- Decida quais comentários precisam ser abordados pelo autor como pré-requisito para a aprovação.
- Escreva "LGTM" (Tudo bem para mim) na conversa quando estiver satisfeito com o estado atual da proposta.
Siga este processo para todas as solicitações de revisão de design. Não aprove projetos que afetam o Bazel se não estiverem no índice de design.
Responsabilidades dos revisores de leads
Você é responsável por tomar a decisão de aprovação ou não sobre a implementação de um design pendente. Se não for possível fazer isso, identifique um delegado adequado (reatribua o PR ao delegado) ou reatribua o bug a um gerenciador do Bazel para disposição posterior.
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 houve 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.
Como rejeitar designs
- Certifique-se de que o autor de RP envie um PR ou envie um 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 suposições inválidas e reenviar").