Como Contribuir

React é um dos primeiros projetos de código aberto do Facebook que está sendo desenvolvido muito ativamente, além de ser usado para entregar código para todos em facebook.com. Nós ainda estamos trabalhando para tornar esse projeto mais transparente e fácil possível, mas ainda não estamos lá. Esperamos que essa documentação torne esse processo de contribuição mais clara e responda algumas perguntas que você possa ter.

Código de Conduta

O Facebook adotou o Convênio do Contribuinte como seu Código de Conduta, e esperamos que os participantes do projeto o adotem. Por favor, leia o texto completo para que você possa entender quais ações serão ou não toleradas.

Desenvolvimento Aberto

Todo trabalho no React acontece diretamente no GitHub. Tanto membros do Core Team quanto contribuidores externos devem enviar pull requests que vão passar pelo mesmo processo de revisão.

Organização de Branches

Nós buscaremos fazer o nosso melhor para manter branch master organizada, com testes passando todas as vezes. Mas para garantir que seremos rápidos, nós faremos mudanças na API nas quais suas aplicações podem não ser compatíveis. Nós recomendamos que você use a versão estável do React.

Se você enviar um pull request, por favor faça contra a branch master. Nós mantemos branches estáveis para versões maiores separadamente, mas não aceitamos pull requests para elas diretamente. Ao invés disso, nós fazemos cherry-pick de mudanças que não quebrem o código da master para a última versão mais estável.

Versionamento Semântico

O React segue o versionamento semântico. Buscar lançar versões de patch para correções de bugs, versões secundárias (minor version) para novos recursos e versões principais (major version) para qualquer alteração de quebra. Quando fazemos alterações significativas, também introduzimos alguns avisos de descontinuidade em uma versão secundária para que nossos usuários tenham conhecimento sobre as próximas alterações e migrem seu código com antecedência.

Nós marcamos com tags qualquer pull request com um marcador que indica se a alteração deve ir para o próximo patch, versão secundária (minor version) ou em uma versão principal (major version). Nós lançamos novas versões de patch a cada poucas semanas, versões secundários a cada poucos meses e versões principais uma ou duas vezes por ano.

Toda mudança significativa é documentada na changelog.

Bugs

Onde Encontrar Problemas Conhecidos

Nós estamos utilizando as GitHub Issues para nossas páginas públicas. Nós vamos ficar de olho e tentar manter claro quando estamos trabalhando internamente na correção de algum bug. Antes de preencher uma nova tarefa, verifique se o problema já existe.

Relatando novos problemas

A melhor maneira de corrigir o problema é fornecer um caso de teste reduzido. Este template no JSFiddle é um excelente ponto de partida.

Bugs de Segurança

O Facebook tem um programa de recompensas para a divulgação segura de bugs de segurança. Com isso em mente, não reporte esses problemas de forma pública. Percorra o processo descrito nessa página.

Como entrar em contato

Há também uma comunidade ativa de usuários do React na plataforma no Discord caso você precise de ajuda.

Propondo uma alteração

Se você pretende alterar a API pública ou fazer alterações não triviais na implementação, recomendamos abrir uma issue. Isso nos permite chegar a um acordo sobre sua proposta antes de colocar um esforço significativo nela.

Se você está apenas corrigindo um bug, não tem problema em enviar uma pull request diretamente, mas ainda sim recomendamos abrir uma issue com detalhes sobre o que você está corrigindo. Isso é útil caso não aceitemos essa correção específica, mas queremos acompanhar o problema.

Seu primeiro Pull Request

Trabalhando em seu primeiro Pull Request. Você pode aprender como desta série de vídeos gratuitos:

Como contribuir para um projeto de código aberto no GitHub

Para ajudar você a se familiarizar com o nosso processo de contribuição, temos uma lista de boas primeiras issues que contém erros que têm um escopo relativamente limitado. Este é um ótimo lugar para começar.

Se você decidir corrigir um bug, por favor, verifique o tópico do comentário caso alguém já esteja trabalhando em uma correção. Se ninguém estiver trabalhando no momento, por favor deixe um comentário dizendo que você pretende trabalhar nele para que outras pessoas não dupliquem sem querer seu esforço.

Se alguém assumir uma issue, mas não fizer o acompanhamento por mais de duas semanas, não há problema em você assumir, mas mesmo assim você ainda deve deixar um comentário.

Enviando um Pull Request

O Core Team está monitorando os pull requests. Analisaremos seu envio e fazermos o merge, solicitaremos alterações ou podemos fechá-la com uma explicação plausível. Para alterações de API, podemos precisar corrigir nossos usos internos no Facebook.com, o que pode causar algum atraso. Faremos o nosso melhor para fornecer atualizações e feedback durante todo o processo.

Antes de enviar o seu pull request, certifique-se de ter feito os seguintes passos:

  1. Faça fork do repositório oficial and criou sua branch da master.
  2. Execute yarn no repositório raíz.
  3. Se você corrigiu um bug ou um código adicionado que deve ser testado, adicione testes!
  4. Certifique-se de que a suíte de teste passe (yarn test). Dica: yarn test --watch TestName é útil no desenvolvimento.
  5. Execute yarn test-prod para testar no ambiente de produção. Suporta as mesmas opções que yarn test.
  6. Se você precisar de um depurador, execute yarn debug-test --watch TestName, abra chrome://inspecte aperte em “Inspecionar”.
  7. Formate seu código com prettier (yarn prettier).
  8. Certifique-se de que seus códigos foram verificados com linters (yarn lint). Dica: yarn linc verifica somente os arquivos alterados.
  9. Rode o Flow para typechecks (yarn flow).
  10. Se ainda não fez, preencha o CLA.

Licença de Acordo de Contribuidor (Contributor License Agreement - CLA)

Para aceitar seu pull request, precisamos que você envie um CLA. Você só precisa fazer isso uma vez, então se você fez isso para outro projeto de código aberto do Facebook, você está pronto para continuar. Se você estiver enviando um pull request pela primeira vez, nos informe que você concluiu o CLA e então podemos fazer uma verificação cruzada com seu GitHub

Preencha sua CLA aqui.

Pré-requisitos de Contribuição

  • Possuir o Node instalado na versão v8.0.0+ e Yarn na versão v1.2.0+.
  • Você deve ter o gcc instalado ou está confortável em instalar um compilador, se necessário. Algumas de nossas dependências podem exigir uma etapa de compilação. No OS X, as Ferramentas de Linha de Comando do Xcode cobrirão isso. No Ubuntu, apt-get install build-essential instalará os pacotes requeridos. Comandos semelhantes devem funcionar em outras distribuições Linux. O Windows irá requerer alguns passos adicionais, veja as instruções de instalação do node-gyp para detalhes.
  • Você deve ser familiarizado com o Git.

Fluxo de Trabalho de Desenvolvimento

Depois de clonar o React, execute yarn para buscar suas dependências. Então, você pode executar vários comandos:

  • yarn lint verifica o estilo de código.
  • yarn linc funciona como o yarn lint, mas é mais rápido porque verifica apenas os arquivos que diferem na sua branch.
  • yarn test executa o conjunto de testes completo.
  • yarn test --watch executa um observador de testes interativo.
  • yarn test <pattern> executa testes com nomes de arquivos correspondentes.
  • yarn test-prod executa testes no ambiente de produção. Suporta todas as mesmas opções que o yarn test.
  • yarn debug-test é como yarn test mas com um depurador. Abra chrome://inspect e clique em “Inspecionar”.
  • yarn flow executa o typecheck do Flow .
  • yarn build cria uma pasta build com todos os pacotes.
  • yarn build react/index,react-dom/index --type=UMD cria compilações UMD somente com o React e ReactDOM.

Recomendamos executar o yarn test (ou suas variações acima) para garantir que você não introduza nenhuma regressão enquanto trabalha na sua mudança. No entanto, pode ser útil testar sua versão do React em um projeto real.

Primeiro, execute yarn build. Isto irá produzir pacotes pré-construídos na pasta build, bem como irá preparar pacotes npm dentro da pasta build/packages.

A maneira mais fácil de testar suas alterações é rodar yarn build react/index,react-dom/index --type=UMD e depois abrir fixtures/packaging/babel-standalone/dev.html. Este arquivo já usa o react.development.js a partir da pasta build para que ele possa pegar suas alterações.

Se você quiser testar suas alterações em seu projeto React já existente, você pode copiar build/dist/react.development.js, build/dist/react-dom.development.js ou qualquer outro build em seu aplicativo e usá-los em vez da versão estável. Se o seu projeto usa o React do npm, você pode excluir react e react-dom em suas dependências e usar yarn link para apontá-los para sua pastabuild local:

cd ~/path_to_your_react_clone/build/node_modules/react
yarn link
cd ~/path_to_your_react_clone/build/node_modules/react-dom
yarn link
cd /path/to/your/project
yarn link react react-dom

Toda vez que você executar yarn build na pasta React, as versões atualizadas aparecerão no node_modules do seu projeto. Você pode então reconstruir seu projeto para testar suas alterações.

Ainda exigimos que seu pull request contenha testes de unidade para qualquer nova funcionalidade. Dessa forma, podemos garantir que não quebremos seu código no futuro.

Guia de Estilo

Usamos um formatador de código automático chamado Prettier. Execute o yarn prettier depois de fazer qualquer alteração no seu código.

Então, nosso linter irá capturar a maioria dos problemas que possam existir em seu código. Você pode verificar o status do seu estilo de código simplesmente executando yarn linc.

No entanto, ainda existem alguns estilos que o linter não consegue captar. Se você não tem certeza sobre alguma coisa, veja o Guia de Estilos do Airbnb para te direcionar no caminho certo.

Vídeo Introdutório

Você pode estar interessado em assistir este pequeno vídeo (26 minutos), que apresenta uma introdução sobre como contribuir para o React.

Destaques no vídeo:

  • 4:12 - Construindo e testando o React localmente
  • 6:07 - Criando e enviando pull requests
  • 8:25 - Organizando código
  • 14:43 - React npm registry
  • 19:15 - Adicionando novos recursos do React

Para obter uma visão geral realista do que é o sentimento de contribuir para o React pela primeira vez, confira essa palestra interessante no ReactNYC.

Pedido de Comentários (Request for Comments - RFC)

Muitas alterações, incluindo correções de bugs e melhorias na documentação, podem ser implementadas e revisadas por meio do fluxo de trabalho normal de pull requests do GitHub.

Algumas mudanças, entretanto, são “substanciais” e pedimos que estas sejam submetidas a um pequeno processo de design e produzam um consenso entre o Core Team do React.

O processo “RFC” (pedido de comentários) destina-se a fornecer um caminho consistente e controlado para que novos recursos entrem no projeto. Você pode contribuir visitando o repositório rfcs.

Licença

Ao contribuir com o React, você concorda que suas contribuições serão licenciadas sob sua licença do MIT.

O que vem a seguir?

Leia a próxima seção para saber como a base de código é organizada.