Contribuir para o código do TensorFlow

Esteja você adicionando uma função de perda, melhorando a cobertura de teste ou escrevendo um RFC para uma grande mudança de design, esta parte do guia do contribuidor o ajudará a começar. Obrigado pelo trabalho e interesse em melhorar o TensorFlow.

Antes de começar

Antes de contribuir com o código-fonte para um projeto do TensorFlow, revise o arquivo CONTRIBUTING.md no repositório GitHub do projeto. Por exemplo, consulte o arquivo CONTRIBUTING.md no repositório principal do TensorFlow. Todos os contribuidores de código são obrigados a assinar um Contributor License Agreement (CLA).

Para evitar a duplicação de trabalho, revise as RFCs atuais ou propostas e entre em contato com os desenvolvedores nos fóruns do TensorFlow ( developers@tensorflow.org ) antes de começar a trabalhar em um recurso não trivial. Somos um pouco seletivos ao decidir adicionar novas funcionalidades, e a melhor maneira de contribuir e ajudar o projeto é trabalhar em problemas conhecidos.

Problemas para novos colaboradores

Novos colaboradores devem procurar as seguintes tags ao procurar uma primeira contribuição para a base de código do TensorFlow. Recomendamos fortemente que os novos contribuidores abordem primeiro os projetos de “boa primeira edição” e “contribuições bem-vindas”; isso ajuda o contribuidor a se familiarizar com o fluxo de trabalho de contribuição e para os desenvolvedores principais se familiarizarem com o contribuidor.

Se você estiver interessado em recrutar uma equipe para ajudar a resolver um problema de grande escala ou um novo recurso, envie um e-mail para o grupo developers@ e revise nossa lista atual de RFCs.

Revisão de código

Novos recursos, correções de bugs e quaisquer outras alterações na base de código estão sujeitas a revisão de código.

A revisão do código contribuído para o projeto como solicitações pull é um componente crucial do desenvolvimento do TensorFlow. Incentivamos qualquer pessoa a começar a revisar o código enviado por outros desenvolvedores, especialmente se o recurso for algo que você provavelmente usará.

Aqui estão algumas perguntas a serem lembradas durante o processo de revisão de código:

  • Queremos isso no TensorFlow? É provável que seja usado? Você, como usuário do TensorFlow, gosta da mudança e pretende usá-la? Essa mudança está no escopo do TensorFlow? O custo de manutenção de um novo recurso valerá seus benefícios?
  • O código é consistente com a API do TensorFlow? As funções públicas, classes e parâmetros são bem nomeados e projetados intuitivamente?

  • Inclui documentação? Todas as funções públicas, classes, parâmetros, tipos de retorno e atributos armazenados são nomeados de acordo com as convenções do TensorFlow e claramente documentados? A nova funcionalidade é descrita na documentação do TensorFlow e ilustrada com exemplos, sempre que possível? A documentação é renderizada corretamente?

  • O código é legível por humanos? A redundância é baixa? Os nomes das variáveis ​​devem ser melhorados para maior clareza ou consistência? Comentários devem ser adicionados? Algum comentário deve ser removido como inútil ou irrelevante?

  • O código é eficiente? Poderia ser reescrito facilmente para ser executado com mais eficiência?

  • O código é compatível com versões anteriores do TensorFlow?

  • O novo código adicionará novas dependências em outras bibliotecas?

Testar e melhorar a cobertura de teste

Testes unitários de alta qualidade são a base do processo de desenvolvimento do TensorFlow. Para isso, usamos imagens do Docker. As funções de teste são nomeadas apropriadamente e são responsáveis ​​por verificar a validade dos algoritmos, bem como as diferentes opções do código.

Todos os novos recursos e correções de bugs devem incluir uma cobertura de teste adequada. Também recebemos contribuições de novos casos de teste ou melhorias em testes existentes. Se você descobrir que nossos testes existentes não estão completos - mesmo que isso não esteja causando um bug no momento - registre um problema e, se possível, uma solicitação pull.

Para obter detalhes específicos dos procedimentos de teste em cada projeto do TensorFlow, consulte os arquivos README.md e CONTRIBUTING.md no repositório do projeto no GitHub.

De preocupações particulares em testes adequados :

  • Todas as funções e classes públicas são testadas?
  • Um conjunto razoável de parâmetros , seus valores, tipos de valores e combinações são testados?
  • Os testes validam que o código está correto e que está fazendo o que a documentação diz que o código deve fazer?
  • Se a mudança for uma correção de bug, um teste de não regressão está incluído?
  • Os testes são aprovados na compilação de integração contínua ?
  • Os testes cobrem todas as linhas de código? Se não, as exceções são razoáveis ​​e explícitas?

Se você encontrar algum problema, considere ajudar o colaborador a entender esses problemas e resolvê-los.

Melhore as mensagens ou logs de erro

Congratulamo-nos com contribuições que melhoram as mensagens de erro e o registro.

Fluxo de trabalho de contribuição

Contribuições de código — correções de bugs, novos desenvolvimentos, melhorias de teste — seguem um fluxo de trabalho centrado no GitHub. Para participar do desenvolvimento do TensorFlow, configure uma conta do GitHub. Então:

  1. Fork o repositório no qual você planeja trabalhar. Vá para a página do repositório do projeto e use o botão Fork . Isso criará uma cópia do repositório, sob seu nome de usuário. (Para obter mais detalhes sobre como bifurcar um repositório, consulte este guia .)

  2. Clone o repositório para o seu sistema local.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Crie uma nova ramificação para manter seu trabalho.

    $ git checkout -b new-branch-name

  4. Trabalhe em seu novo código. Escreva e execute testes.

  5. Confirme suas alterações.

    $ git add -A

    $ git commit -m "commit message here"

  6. Envie suas alterações para o repositório do GitHub.

    $ git push origin branch-name

  7. Abra uma solicitação de pull (PR). Acesse o repositório do projeto original no GitHub. Haverá uma mensagem sobre sua ramificação enviada recentemente, perguntando se você gostaria de abrir uma solicitação de pull. Siga as instruções, compare os repositórios e envie o PR. Isso enviará um e-mail para os committers. Você pode considerar enviar um e-mail para a lista de discussão para obter mais visibilidade. (Para obter mais detalhes, consulte o guia do GitHub sobre PRs .

  8. Os mantenedores e outros colaboradores revisarão seu PR . Participe da conversa e tente fazer as alterações solicitadas . Assim que o PR for aprovado, o código será mesclado.

Antes de trabalhar em sua próxima contribuição , certifique-se de que seu repositório local esteja atualizado.

  1. Configure o controle remoto upstream. (Você só precisa fazer isso uma vez por projeto, não sempre.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Alterne para a ramificação mestre local.

    $ git checkout master

  3. Puxe para baixo as alterações de upstream.

    $ git pull upstream master

  4. Envie as alterações para sua conta do GitHub. (Opcional, mas uma boa prática.)

    $ git push origin master

  5. Crie uma nova ramificação se estiver iniciando um novo trabalho.

    $ git checkout -b branch-name

Recursos adicionais do git e do GitHub:

Lista de verificação do colaborador