Se você planeja adicionar, alterar ou remover um recurso voltado para o usuário ou fazer uma mudança arquitetônica significativa no Bazel, precisa escrever um documento de design e analisá-lo antes de enviar a alteração.
Veja alguns exemplos de mudanças significativas:
- Adição ou exclusão de regras de compilação nativas
- Alterações interruptivas nas regras nativas
- Mudanças em uma semântica de regra de compilação 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 API Starlark
- Mudanças que podem ter um efeito generalizado no desempenho do Bazel ou no uso da memória (para melhorar ou piorar)
- Mudanças nas APIs internas mais usadas
- Mudanças nas sinalizações e na interface de linha de comando.
Motivos para revisões de design
Ao escrever um documento de design, é possível 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 em arquivos 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. 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 só 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 fora da equipe principal. Esses colaboradores têm níveis variados de experiência.
- A equipe do Bazel tem níveis de especialização diferentes. Nenhum membro da equipe tem uma compreensão completa de cada canto do Bazel.
- As alterações 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:
- todas as solicitações de recursos recebem um nível de análise minucioso.
- as pessoas certas vão considerar os designs antes de investirmos em uma implementação que não funcione.
Para ajudar você a começar, confira os documentos de design no Repositório de propostas do Bazel. Os designs estão em andamento, então os detalhes da implementação podem mudar ao longo do tempo e com feedback. Os documentos de design publicados capturam o design inicial, e não as mudanças em andamento à medida que os designs são implementados. Sempre consulte a documentação para ver descrições das funcionalidades atuais do Bazel.
Fluxo de trabalho de colaborador
Como colaborador, você pode escrever um documento de design, enviar solicitações de envio e revisores de solicitações 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 mudança
- lista de revisores, incluindo um (e apenas um) revisor líder
- status atual (rascunho, em análise, aprovado, rejeitado, sendo implementado, implementado)
- link para a conversa (será adicionado após o anúncio)
O documento pode ser escrito como um arquivo do Documentos Google legível ou usando o Markdown. Veja abaixo uma comparação entre o Markdown / 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 o arquivo de marcação ou um link de documento ao seu PR.
Quando possível, escolha um revisor líder e copie outros revisores. Se você não escolher um revisor de lead, um mantenedor do Bazel atribuirá um ao PR.
Depois de criar sua PR, os revisores podem fazer comentários preliminares durante a revisão do código. Por exemplo, o revisor líder pode sugerir revisores extras ou apontar informações que estão faltando. 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 seja perfeita ou que seja aprovada, isso significa que ela contém informações suficientes para iniciar a discussão.
Anunciar a nova proposta
Envie um aviso 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 os revisores
Qualquer pessoa interessada pode comentar sua proposta. Tente responder a perguntas, esclarecer a proposta e resolver problemas.
A conversa deve acontecer na conversa. Se a proposta estiver em um arquivo do Documentos Google, comentários poderão ser usados. Comentários anônimos são permitidos.
Atualizar o status
Crie uma nova PR para atualizar o status da proposta, quando a iteração for concluída. Envie o PR ao mesmo revisor líder e coloque em cópia os outros revisores.
Para aceitar oficialmente a proposta, o revisor líder aprova o PR depois de garantir que os outros revisores concordam com a decisão.
É necessário que haja pelo menos uma semana entre o primeiro aviso 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 da proposta ser aceita, por exemplo, como uma prova de conceito ou experimento. No entanto, não é possível enviar a alteração antes da conclusão da análise.
Como escolher um revisor de leads
Um revisor líder deve ser um especialista no domínio que seja:
- Conhecimento dos subsistemas relevantes.
- Objetivo e capaz de fornecer feedback construtivo
- Disponível durante todo o período de análise para conduzir o processo
Verifique os contatos em busca de vários rótulos de equipe.
Markdown x Documentos Google
Decida o que é melhor para você, já que ambos são aceitos.
Benefícios do uso do Documentos Google:
- Eficaz para a discussão de ideias, já que é fácil começar a usá-lo.
- Edição colaborativa.
- Iteração rápida.
- Maneira fácil de sugerir edições.
Benefícios do uso de 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.
- Pesquisa fácil com mecanismos de pesquisa.
- Preparado para o futuro: o texto simples não depende de nenhuma ferramenta específica e não precisa de uma conexão de Internet.
- É possível atualizá-las mesmo que o autor não esteja mais disponível.
- Eles podem ser processados automaticamente (atualizar/detectar links inativos, buscar lista de autores etc.).
Você pode optar por iterar em um arquivo do Documentos Google e depois fazer a conversão para o Markdown para posterior.
Como usar o Documentos Google
Para manter a 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 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 do GitHub de Markdown (especificação).
Crie um PR para atualizar um documento existente. Os revisores de documentos precisam revisar as alterações significativas. Mudanças triviais, como erros de digitação e formatação, podem ser aprovadas por qualquer pessoa.
Fluxo de trabalho do avaliador
Um revisor comenta e analisa os documentos de design.
Responsabilidades gerais de avaliador
Você é responsável por revisar os documentos de design, solicitar mais informações, se necessário, e aprovar um design aprovado no processo de revisão.
Quando você recebe uma nova proposta
- Dê uma olhada rápida no documento.
- Comente se informações importantes estiverem ausentes ou se o design não corresponder às metas do projeto.
- Sugira mais revisores.
- Aprove o PR quando ele estiver pronto para revisão.
Durante o processo de revisão
- Converse com o autor do projeto sobre problemas problemáticos ou que precisam de esclarecimento.
- Se apropriado, convide comentários de não revisores que precisam estar cientes do design.
- Decida quais comentários precisam ser abordados pelo autor como pré-requisito para aprovação.
- Escreva "LGTM" (Parece bom) na linha de execução de discussão quando você 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 líder
Você é responsável por tomar a decisão de executar ou não a implementação de um design pendente. Se você não conseguir fazer isso, identifique um representante adequado (reatribua o PR ao delegado) ou reatribua o bug a um gerenciador do Bazel para mais disposição.
Durante o processo de revisão
- Verifique se o processo de iteração de comentário e design avança de forma construtiva.
- Antes da aprovação, garanta que as preocupações de outros revisores tenham sido resolvidas.
Após a aprovação de todos os revisores
- Verifique se há pelo menos uma semana desde o anúncio na lista de e-mails.
- O PR precisa atualizar o status.
- Aprove o PR enviado pelo autor da proposta.
Rejeitar designs
- Verifique se o autor do PR envia um PR; ou envie a ele um PR.
- O PR 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 especificando as próximas etapas, se houver (como "rever suposições inválidas e reenviar").