Cada novo recurso do TensorFlow começa como uma solicitação de comentário (RFC).
Um RFC é um documento que descreve um requisito e as mudanças propostas que irão resolvê-lo. Especificamente, o RFC irá:
- Ser formatado de acordo com o modelo RFC .
- Ser enviado como uma solicitação pull para o diretório community / rfcs .
- Esteja sujeito a discussão e uma reunião de revisão antes da aceitação.
O objetivo de uma solicitação de comentários (RFC) do TensorFlow é envolver a comunidade do TensorFlow no desenvolvimento, obtendo feedback das partes interessadas e especialistas e comunicando as alterações de design de maneira ampla.
Como enviar um RFC
Antes de enviar um RFC, discuta seus objetivos com os contribuidores e mantenedores do projeto e obtenha feedback antecipado. Use a lista de discussão do desenvolvedor para o projeto em questão (developers@tensorflow.org, ou a lista do SIG relevante).
Elabore seu RFC.
- Leia os critérios de revisão do projeto
- Siga o modelo RFC .
- Nomeie seu arquivo RFC
YYYYMMDD-descriptive-name.md
, ondeYYYYMMDD
é a data de envio edescriptive-name
relacionado ao título de seu RFC. (Por exemplo, se seu RFC for intitulado Parallel Widgets API , você pode usar o nome de arquivo20180531-parallel-widgets.md
. - Se você tiver imagens ou outros arquivos auxiliares, crie um diretório no formato
YYYYMMDD-descriptive-name
para armazenar esses arquivos.
Depois de escrever o rascunho da RFC, obtenha feedback dos mantenedores e colaboradores antes de enviá-lo.
Escrever código de implementação não é um requisito, mas pode ajudar a criar discussões.
Recrute um patrocinador.
- Um patrocinador deve ser o mantenedor do projeto.
- Identifique o patrocinador na RFC, antes de postar o PR.
Você pode postar um RFC sem um patrocinador, mas se dentro de um mês após postar o PR ainda não houver patrocinador, ele será fechado.
Envie seu RFC como uma solicitação pull para tensorflow / community / rfcs .
Inclua a tabela de cabeçalho e o conteúdo da seção Objetivo no comentário de sua solicitação de pull, usando Markdown. Para obter um exemplo, consulte este RFC de exemplo . Inclui os identificadores do GitHub de coautores, revisores e patrocinadores.
Na parte superior do PR, identifique quanto tempo será o período de comentários. Isso deve levar no mínimo duas semanas a partir da publicação do PR.
Envie um e-mail para a lista de discussão do desenvolvedor com uma breve descrição, um link para o PR e um pedido de revisão. Siga o formato das correspondências anteriores, como você pode ver neste exemplo .
O patrocinador solicitará uma reunião do comitê de revisão, não antes de duas semanas após a publicação do RFC PR. Se a discussão estiver animada, espere até que ela esteja resolvida antes de ir para a revisão. O objetivo da reunião de revisão é resolver questões menores; deve-se chegar a um consenso sobre as questões principais de antemão.
A reunião pode aprovar o RFC, rejeitá-lo ou exigir alterações antes de ser considerado novamente. Os RFCs aprovados serão mesclados com a comunidade / rfcs e os RFCs rejeitados terão seus PRs fechados.
Participantes RFC
Muitas pessoas estão envolvidas no processo de RFC:
Autor RFC - um ou mais membros da comunidade que escrevem um RFC e estão comprometidos em defendê-lo durante o processo
Patrocinador do RFC - um mantenedor que patrocina o RFC e o orienta durante o processo de revisão do RFC
comitê de revisão - um grupo de mantenedores que tem a responsabilidade de recomendar a adoção do RFC
Qualquer membro da comunidade pode ajudar fornecendo feedback sobre se a RFC atenderá às suas necessidades.
Patrocinadores RFC
Um patrocinador é um mantenedor do projeto responsável por garantir o melhor resultado possível do processo RFC. Isso inclui:
- Defender o design proposto.
- Orientar o RFC para aderir às convenções de design e estilo existentes.
- Orientar o comitê de revisão para chegar a um consenso produtivo.
- Se mudanças forem solicitadas pelo comitê de revisão, certifique-se de que sejam feitas e busque a aprovação subsequente dos membros do comitê.
- Se o RFC for movido para implementação:
- Garantir que a implementação proposta esteja de acordo com o design.
- Coordenar com as partes apropriadas para uma implementação bem-sucedida do terreno
Comitês de revisão de RFC
O comitê de revisão decide por consenso se aprova, rejeita ou solicita alterações. Eles são responsáveis por:
- Garantir que itens substantivos de feedback público foram considerados.
- Adicionando suas notas de reunião como comentários para o PR.
- Fornecendo razões para suas decisões.
A constituição de um comitê de revisão pode mudar de acordo com o estilo específico de governança e liderança de cada projeto. Para o TensorFlow principal, o comitê consistirá em colaboradores do projeto TensorFlow com experiência na área de domínio em questão.
Membros da comunidade e o processo RFC
O objetivo dos RFCs é garantir que a comunidade seja bem representada e atendida por novas mudanças no TensorFlow. É responsabilidade dos membros da comunidade participar da revisão das RFCs quando tiverem interesse no resultado.
Os membros da comunidade interessados em um RFC devem:
- Forneça feedback o mais rápido possível para permitir tempo adequado para consideração.
- Leia as RFCs completamente antes de fornecer feedback.
- Seja civilizado e construtivo .
Implementando novos recursos
Assim que um RFC for aprovado, a implementação pode começar.
Se você estiver trabalhando em um novo código para implementar um RFC:
- Certifique-se de compreender o recurso e o design aprovado no RFC. Faça perguntas e discuta a abordagem antes de começar a trabalhar.
- Novos recursos devem incluir novos testes de unidade que verificam se o recurso funciona conforme o esperado. É uma boa ideia escrever esses testes antes de escrever o código.
- Siga o Guia de estilo de código do TensorFlow
- Adicione ou atualize a documentação API relevante. Consulte o RFC na nova documentação.
- Siga todas as outras diretrizes estabelecidas no arquivo
CONTRIBUTING.md
noCONTRIBUTING.md
do projeto para o qual você está contribuindo. - Execute testes de unidade antes de enviar seu código.
- Trabalhe com o patrocinador da RFC para obter o novo código com sucesso.
Mantendo a fasquia elevada
Embora encorajemos e celebremos cada contribuidor, o nível de aceitação do RFC é mantido intencionalmente alto. Um novo recurso pode ser rejeitado ou precisar de revisão significativa em qualquer um desses estágios:
- Conversas iniciais de design na lista de e-mails relevante.
- Falha ao recrutar um patrocinador.
- Objeções críticas durante a fase de feedback.
- Falha em obter consenso durante a revisão do projeto.
- Preocupações levantadas durante a implementação (por exemplo: incapacidade de obter compatibilidade com versões anteriores, preocupações com a manutenção).
Se esse processo estiver funcionando bem, espera-se que os RFCs falhem nos estágios anteriores, em vez de posteriores. Uma RFC aprovada não é garantia de um compromisso de implementação, e a aceitação de uma implementação de RFC proposta ainda está sujeita ao processo normal de revisão de código.
Se você tiver alguma dúvida sobre este processo, sinta-se à vontade para perguntar na lista de discussão de desenvolvedores ou envie um problema para tensorflow / comunidade .