Cómo contribuir

React es uno de los primeros proyectos de código abierto de Facebook que si bien está siendo desarrollado muy activamente, al mismo tiempo se utiliza para crear código que les llega a todos en facebook.com. Todavía estamos trabajando en los problemas para hacer que la contribución a este proyecto sea lo más fácil y transparente posible, pero aún no hemos llegado a ese punto. Esperamos que este documento haga que el proceso de contribución sea claro y responda algunas preguntas que pueda tener.

Código de conducta

Facebook ha adoptado el Convenio del Contribuidor como su Código de Conducta, que esperamos que los participantes del proyecto cumplan. Por favor, lee el texto completo para que puedas comprender qué acciones serán o no toleradas.

Desarrollo abierto

Todo el trabajo en React sucede directamente en GitHub. Tanto los miembros del equipo central como los colaboradores externos envían pull requests que pasan por el mismo proceso de revisión.

Versionado semántico

React utiliza versionado semántico. Lanzamos versiones con parches para arreglos de errores críticos, versiones menores para nuevas funcionalidades o cambios no esenciales, y versiones mayores para cualquier cambio disruptivo. Cuando creamos cambios disruptivos, también agregamos alertas de obsolescencia para que los usuarios aprendan sobre los cambios que vienen y migren su código con antelación. Aprende más sobre nuestro compromiso con la estabilidad y la migración incremental en nuestra política de versionado.

Cada cambio significativo es documentado en el archivo de cambios.

Organización de ramas

Envía todos los cambios directo a la rama de master. No utilizamos ramas separadas para desarrollo o para lanzamientos futuros. Hacemos nuestro mejor esfuerzo para mantener master en buena forma, con todas las pruebas pasando.

El código que llega a master debe ser compatible con la última versión estable. Puede contener funcionalidades adicionales, pero no cambios disruptivos. Debemos ser capaces de lanzar una nueva versión menor desde la punta de master en cualquier momento.

Banderas de funcionalidades

Para mantener la rama master en un estado de lanzamiento, los cambios disruptivos y funcionalidades experimentales deben ser puestas ante una bandera de funcionalidad.

Las banderas de funcionalidad están definidas en packages/shared/ReactFeatureFlags.js. Algunos compilados de React pueden habilitar diferentes conjuntos de banderas; por ejemplo, el compilado de React Native puede ser configurado diferente a como es configurado React DOM. Estas banderas son encontradas en packages/shared/forks. Las banderas de funcionalidad son escritas estáticamente con Flow, por lo que puedes ejecutar yarn flow para confirmar que has actualizado los archivos necesarios.

El sistema de compilado de React quitará las ramas de funcionalidades desactivadas antes de publicar. Un trabajo de integración continua se ejecuta con cada commit para comprobar los cambios en el tamaño del paquete. Puedes usar el cambio en el tamaño como una señal de que una funcionalidad fue puesta correctamente.

Errores

Dónde encontrar problemas conocidos

Estamos utilizando el sistema de incidencias de GitHub para nuestros errores públicos. Mantenemos una estrecha vigilancia sobre esto y tratamos de avisar cuando tenemos una solución interna en curso. Antes de hacer un nuevo reporte, asegúrate de que tu problema no exista ya.

Reportando nuevas incidencias

La mejor manera de solucionar tu error es proporcionar un caso de prueba reducido. Esta plantilla JSFiddle es un gran punto de partida.

Errores de seguridad

Facebook tiene un programa de recompensas para la divulgación segura de errores de seguridad. Con esto en mente, por favor, no abras incidencias públicas. Sigue el proceso descrito en esa página.

Cómo entrar en contacto

También hay una comunidad activa de usuarios de React en la plataforma de chat Discord en caso de que necesites ayuda con React.

Proponer un cambio

Si tiene la intención de cambiar la API pública o realizar cambios no triviales en la implementación, recomendamos abrir una incidencia. Esto nos permite llegar a un acuerdo sobre tu propuesta antes que le pongas un gran esfuerzo.

Si solo estás solucionando un error, está bien enviar un pull request de inmediato, pero seguimos recomendando que abras una incidencia que detalle que es lo que estás solucionando. Esto es útil en caso de que no aceptemos esa solución en particular, pero aún queramos hacer el seguimiento del problema.

Tu primer pull request

¿Trabajando en tu primer pull request? Puedes aprender cómo en esta serie de videos gratis:

Cómo contribuir a un proyecto de código abierto en GitHub

Para ayudarte a familiarizarte con nuestro proceso de contribución, tenemos una lista de incidencias adecuadas para comenzar que contienen errores que tienen un alcance relativamente limitado. Este es un gran lugar para empezar.

Si decides solucionar una incidencia, asegúrate de revisar el hilo de comentarios en caso de que alguien ya esté trabajando en una solución. Si nadie está trabajando en ello en este momento, deja un comentario que indique que deseas trabajar en ella para que otras personas no dupliquen accidentalmente su esfuerzo.

Si alguien reclama una incidencia pero no hace un seguimiento por más de dos semanas, está bien que te hagas cargo pero aún así debes dejar un comentario.

Enviar un pull request

El equipo principal está monitoreando los pull requests. Revisaremos tu pull request y haremos un merge, solicitaremos cambios o lo cerraremos con una explicación. Para los cambios de API, es posible que tengamos que arreglar nuestros usos internos en Facebook.com, lo que podría causar algún retraso. Haremos nuestro mejor esfuerzo para proporcionar actualizaciones y comentarios durante todo el proceso.

Antes de enviar un pull request, asegúrate de que se haga lo siguiente:

  1. Haz un fork del repositorio y crea tu rama a partir de master.
  2. Ejecuta yarn en la raíz del repositorio.
  3. Si has corregido un error o has agregado un código que debería probarse, ¡agrega pruebas!
  4. Asegúrate de que el conjunto de pruebas pasa (yarn test). Consejo: yarn test --watch TestName es útil en desarrollo.
  5. Ejecuta yarn test-prod para probar en el entorno de producción. Es compatible con las mismas opciones que yarn test.
  6. Si necesitas un depurador, ejecuta yarn debug-test --watch TestName, abre chrome://inspect y presiona “Inspeccionar”.
  7. Formatea tu código con prettier (yarn prettier).
  8. Asegúrate de ejecutar lint en tu código (yarn lint). Consejo: yarn linc para verificar solo los archivos modificados.
  9. Ejecuta los controles de tipo de Flow (yarn flow).
  10. Si aún no lo has hecho, completa el CLA.

Acuerdo de Licencia de Contribuidor (CLA)

Para aceptar tu pull request, necesitamos que envíes un CLA. Solo necesitas hacer esto una vez, así que si lo has hecho para otro proyecto de código abierto de Facebook, estás listo. Si estás enviando un pull request por primera vez, haznos saber que has completado el CLA y podemos verificarlo con tu nombre de usuario de GitHub.

Completa tu CLA aquí.

Prerequisitos para contribuir

  • Tienes Node instalado con v8.0.0+ y Yarn con v1.2.0+.
  • Tienes gcc instalado o te sientes cómodo instalando un compilador si es necesario. Algunas de nuestras dependencias pueden requerir un paso de compilación. En OS X, las herramientas de línea de comandos de Xcode cubrirán esto. En Ubuntu, apt-get install build-essential instalará los paquetes necesarios. Comandos similares deberían funcionar en otras distribuciones de Linux. Windows requerirá algunos pasos adicionales, consulta las instrucciones de instalación de node-gyp para obtener más información.
  • Estás familiarizado con Git.

Flujo de trabajo de desarrollo

Después de clonar React, ejecuta yarn para obtener sus dependencias. A continuación, puedes ejecutar varios comandos:

  • yarn lint comprueba el estilo del código.
  • yarn linc es comoyarn lint pero más rápido, porque solo verifica los archivos que difieren en tu rama.
  • yarn test ejecuta el conjunto total de pruebas.
  • yarn test --watch ejecuta un observador de pruebas interactivo.
  • yarn test <pattern> ejecuta pruebas con nombres de archivos que coincidan.
  • yarn test-prod ejecuta pruebas en el entorno de producción. Es compatible con todas las mismas opciones que yarn test.
  • yarn debug-test es igual queyarn test pero con un depurador. Abre chrome://inspect y presiona “Inspeccionar”.
  • yarn flow ejecuta todas las comprobaciones de tipos de Flow.
  • yarn build crea una carpetabuild con todos los paquetes.
  • yarn build react/index,react-dom/index --type=UMD crea las compilaciones UMD solo de React y ReactDOM.

Recomendamos ejecutar yarn test (o sus variaciones anteriores) para asegurarte de no introducir ninguna regresión mientras trabajas en tu cambio. Sin embargo, puede ser útil probar tu compilación de React en un proyecto real.

En primer lugar, ejecuta yarn build. Esto producirá paquetes precompilados en la carpeta build, así como también preparará paquetes npm dentro de build/packages.

La forma más fácil de probar tus cambios es ejecutar yarn build react/index,react-dom/index --type=UMD y luego abrir fixtures/packaging/babel-standalone/dev.html. Este archivo ya utiliza react.development.js de la carpetabuild por lo que recogerá tus cambios.

Si deseas probar los cambios en tu proyecto React existente, puedes copiar build/dist/react.development.js,build/dist/react-dom.development.js, o cualquier otro producto de compilación en tu aplicación y usarlos en lugar de la versión estable. Si tu proyecto usa React desde npm, puedes eliminar react yreact-dom en sus dependencias y usar yarn link para apuntarlos a tu carpeta local build:

cd ~/ruta_a_tu_clon_react/build/node_modules/react
yarn link
cd ~/ruta_a_tu_clon_react/build/node_modules/react-dom
yarn link
cd /ruta/a/tu/proyecto
yarn link react react-dom

Cada vez que ejecutes yarn build en la carpeta React, las versiones actualizadas aparecerán dentro de node_modules en tu proyecto. A continuación, puedes reconstruir tu proyecto para probar tus cambios.

Aún requerimos que tu pull request contenga pruebas unitarias para cualquier funcionalidad nueva. De esta manera podemos asegurarnos de que tu código no falle en el futuro.

Guía de estilo

Utilizamos un formateador de código automático llamado Prettier. Ejecuta yarn prettier después de realizar cualquier cambio en el código.

Luego, nuestra guía detectará la mayoría de los problemas que puedan existir en tu código. Puedes verificar el estado de tu estilo de código simplemente ejecutando yarn linc.

Sin embargo, todavía hay algunos estilos que el linter no puede recoger. Si no estás seguro de algo, consulta la Guía de estilo de Airbnb que te guiará en la dirección correcta.

Video introductorio

Es posible que te interese ver este breve video (26 minutos) que brinda una introducción sobre cómo contribuir a React.

Momentos destacados del video:

  • 4:12 - Construir y probar React localmente
  • 6:07 - Crear y enviar pull requests
  • 8:25 - Organizar el código
  • 14:43 - Registro de React en npm
  • 19:15 - Adición de nuevas funcionalidades a React

Para obtener una descripción realista de lo que se siente contribuir a React por primera vez, echa un vistazo a esta entretenida charla de ReactNYC.

Solicitud de comentarios (RFC)

Muchos cambios, incluyendo correcciones de errores y mejoras en la documentación, se pueden implementar y revisar a través del flujo de trabajo normal de pull request de GitHub.

Sin embargo, algunos cambios son “sustanciales”, y pedimos que se sometan a un proceso de diseño y produzcan un consenso entre el equipo central de React.

El proceso “RFC” (solicitud de comentarios) tiene como objetivo proporcionar una ruta coherente y controlada para que las nuevas características ingresen al proyecto. Puedes contribuir visitando el repositorio rfcs.

Licencia

Al contribuir a React, aceptas que tus contribuciones se otorgarán bajo su licencia MIT.

¿Qué hay luego?

Lee la sección siguiente para saber cómo está organizada la base de código.