Contribuir al código de TensorFlow

Ya sea que esté agregando una función de pérdida, mejorando la cobertura de pruebas o escribiendo una RFC para un cambio de diseño importante, esta sección de la guía para colaboradores le ayudará a comenzar. Gracias por su trabajo e interés en mejorar TensorFlow.

Antes de empezar

Antes de contribuir con código fuente a un proyecto de TensorFlow, revise el archivo CONTRIBUTING.md en el repositorio de GitHub del proyecto. Por ejemplo, consulte el archivo CONTRIBUTING.md en el repositorio principal de TensorFlow. Todos los contribuyentes de código deben firmar un Acuerdo de Licencia de Colaborador (CLA).

Para evitar la duplicación de trabajo, revise las RFC actuales o propuestas y contacte a los desarrolladores en los foros de TensorFlow ( developers@tensorflow.org ) antes de comenzar a trabajar en una función importante. Somos algo selectivos al decidir añadir nuevas funcionalidades, y la mejor manera de contribuir y ayudar al proyecto es trabajar en los problemas conocidos.

Problemas para los nuevos colaboradores

Los nuevos colaboradores deben buscar las siguientes etiquetas al buscar su primera contribución al código base de TensorFlow. Recomendamos encarecidamente que los nuevos colaboradores aborden primero los proyectos de "buena primera incidencia" y "bienvenidas las contribuciones". Esto les ayuda a familiarizarse con el flujo de trabajo de las contribuciones y a los desarrolladores principales a familiarizarse con ellos.

Si está interesado en reclutar un equipo para ayudar a abordar un problema a gran escala o una nueva característica, envíe un correo electrónico al grupo developers@ y revise nuestra lista actual de RFC.

Revisión de código

Las nuevas características, correcciones de errores y cualquier otro cambio en la base del código están sujetos a revisión de código.

Revisar el código aportado al proyecto como solicitudes de incorporación de cambios es un componente crucial del desarrollo de TensorFlow. Animamos a todos a empezar a revisar el código enviado por otros desarrolladores, especialmente si la función es algo que probablemente usarán.

A continuación se presentan algunas preguntas a tener en cuenta durante el proceso de revisión del código:

  • ¿Queremos esto en TensorFlow? ¿Es probable que se use? ¿Como usuario de TensorFlow, le gusta el cambio y piensa usarlo? ¿Este cambio está dentro del alcance de TensorFlow? ¿Valdrá la pena el costo de mantener una nueva función?
  • ¿El código es coherente con la API de TensorFlow? ¿Las funciones, clases y parámetros públicos tienen nombres correctos y un diseño intuitivo?

  • ¿Incluye documentación? ¿ Todas las funciones públicas, clases, parámetros, tipos de retorno y atributos almacenados se nombran según las convenciones de TensorFlow y están claramente documentados? ¿Se describen las nuevas funcionalidades en la documentación de TensorFlow y se ilustran con ejemplos, siempre que sea posible? ¿La documentación se representa correctamente?

  • ¿Es el código legible? ¿Tiene poca redundancia? ¿Deberían mejorarse los nombres de las variables para mayor claridad y coherencia? ¿Deberían añadirse comentarios? ¿Deberían eliminarse los comentarios por ser inútiles o superfluos?

  • ¿Es eficiente el código? ¿ Podría reescribirse fácilmente para que funcione con mayor eficiencia?

  • ¿El código es compatible con versiones anteriores de TensorFlow?

  • ¿El nuevo código agregará nuevas dependencias en otras bibliotecas?

Probar y mejorar la cobertura de las pruebas

Las pruebas unitarias de alta calidad son un pilar fundamental del proceso de desarrollo de TensorFlow. Para ello, utilizamos imágenes Docker. Las funciones de prueba tienen nombres apropiados y se encargan de comprobar la validez de los algoritmos, así como de las diferentes opciones del código.

Todas las nuevas funciones y correcciones de errores deben incluir una cobertura de pruebas adecuada. También agradecemos las contribuciones de nuevos casos de prueba o mejoras a las pruebas existentes. Si descubre que nuestras pruebas existentes no están completas, incluso si esto no causa un error, por favor, informe de un problema y, si es posible, envíe una solicitud de incorporación de cambios.

Para conocer los detalles específicos de los procedimientos de prueba en cada proyecto de TensorFlow, consulte los archivos README.md y CONTRIBUTING.md en el repositorio del proyecto en GitHub.

De particular preocupación en lo que respecta a la realización de pruebas adecuadas :

  • ¿Se prueban todas las funciones y clases públicas ?
  • ¿Se prueba un conjunto razonable de parámetros , sus valores, tipos de valores y combinaciones?
  • ¿Las pruebas validan que el código es correcto y que hace lo que la documentación dice que el código debe hacer?
  • Si el cambio es una corrección de error, ¿se incluye una prueba de no regresión ?
  • ¿Las pruebas pasan la compilación de integración continua ?
  • ¿Las pruebas cubren cada línea de código? De no ser así, ¿son las excepciones razonables y explícitas?

Si encuentra algún problema, considere ayudar al colaborador a comprender esos problemas y resolverlos.

Mejorar los mensajes de error o registros

Agradecemos contribuciones que mejoren los mensajes de error y el registro.

Flujo de trabajo de contribución

Las contribuciones al código (corrección de errores, desarrollo de nuevos componentes, mejora de pruebas) siguen un flujo de trabajo centrado en GitHub. Para participar en el desarrollo de TensorFlow, crea una cuenta de GitHub. Después:

  1. Bifurca el repositorio en el que planeas trabajar. Ve a la página del repositorio del proyecto y usa el botón Bifurcar . Esto creará una copia del repositorio con tu nombre de usuario. (Para más detalles sobre cómo bifurcar un repositorio, consulta esta guía ).

  2. Clona el repositorio en tu sistema local.

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

  3. Crea una nueva rama para guardar tu trabajo.

    $ git checkout -b new-branch-name

  4. Trabaja en tu nuevo código. Escribe y ejecuta pruebas.

  5. Confirme sus cambios.

    $ git add -A

    $ git commit -m "commit message here"

  6. Envía tus cambios a tu repositorio de GitHub.

    $ git push origin branch-name

  7. Abre una solicitud de extracción (PR). Ve al repositorio original del proyecto en GitHub. Verás un mensaje sobre tu rama recientemente subida, preguntándote si deseas abrir una solicitud de extracción. Sigue las indicaciones, compara los repositorios y envía la PR. Esto enviará un correo electrónico a los autores de la confirmación. Puedes considerar enviar un correo electrónico a la lista de correo para mayor visibilidad. (Para más detalles, consulta la guía de GitHub sobre PR) .

  8. Los mantenedores y otros colaboradores revisarán su solicitud de incorporación de cambios . Participe en la conversación e intente realizar los cambios solicitados . Una vez aprobada la solicitud de incorporación de cambios, se fusionará el código.

Antes de trabajar en su próxima contribución , asegúrese de que su repositorio local esté actualizado.

  1. Configura el control remoto ascendente. (Solo tienes que hacer esto una vez por proyecto, no siempre).

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

  2. Cambiar a la rama maestra local.

    $ git checkout master

  3. Extraiga los cambios desde arriba.

    $ git pull upstream master

  4. Sube los cambios a tu cuenta de GitHub. (Opcional, pero recomendable).

    $ git push origin master

  5. Crea una nueva rama si estás iniciando un nuevo trabajo.

    $ git checkout -b branch-name

Recursos adicionales git y GitHub:

Lista de verificación para colaboradores