Cada nueva función de TensorFlow comienza como una solicitud de comentario (RFC).
Un RFC es un documento que describe un requisito y los cambios propuestos que lo resolverán. Específicamente, el RFC:
- Estar formateado de acuerdo con la plantilla RFC .
- Ser enviado como una solicitud de extracción al directorio community / rfcs .
- Estar sujeto a discusión y una reunión de revisión antes de la aceptación.
El propósito de una solicitud de comentarios (RFC) de TensorFlow es involucrar a la comunidad de TensorFlow en el desarrollo, obteniendo comentarios de las partes interesadas y expertos, y comunicando los cambios de diseño de manera amplia.
Cómo enviar una RFC
Antes de enviar un RFC, discuta sus objetivos con los colaboradores y mantenedores del proyecto y obtenga retroalimentación temprana. Utilice la lista de correo del desarrollador para el proyecto en cuestión (firstname.lastname@example.org, o la lista del SIG relevante).
Redacte su RFC.
- Leer los criterios de revisión de diseño
- Siga la plantilla RFC .
- Nombra tu archivo RFC
YYYYMMDD-descriptive-name.md
, dondeYYYYMMDD
es la fecha de envío ydescriptive-name
relaciona con el título de tu RFC. (Por ejemplo, si su RFC se titula Parallel Widgets API , puede usar el nombre de archivo20180531-parallel-widgets.md
. - Si tiene imágenes u otros archivos auxiliares, cree un directorio con el formato
YYYYMMDD-descriptive-name
en el que almacenar esos archivos.
Después de escribir el borrador de RFC, obtenga comentarios de los mantenedores y colaboradores antes de enviarlo.
Escribir código de implementación no es un requisito, pero puede ayudar a diseñar discusiones.
Recluta un patrocinador.
- Un patrocinador debe ser un mantenedor del proyecto.
- Identifique al patrocinador en el RFC, antes de publicar el PR.
Puede publicar un RFC sin un patrocinador, pero si dentro de un mes de la publicación de la PR todavía no existe un patrocinador, que se cerrará.
Envíe su RFC como una solicitud de extracción a tensorflow / community / rfcs .
Incluya la tabla de encabezado y el contenido de la sección Objetivo en el comentario de su solicitud de extracción, utilizando Markdown. Para ver un ejemplo, consulte este RFC de ejemplo . Incluya los identificadores de GitHub de coautores, revisores y patrocinadores.
En la parte superior del PR, identifique la duración del período de comentarios. Esto debería ser un mínimo de dos semanas a partir de la publicación del PR.
Envíe un correo electrónico a la lista de correo del desarrollador con una breve descripción, un enlace al RP y una solicitud de revisión. Siga el formato de los correos anteriores, como puede ver en este ejemplo .
El patrocinador solicitará una reunión del comité de revisión, no antes de dos semanas después de que se publique el RFC PR. Si la discusión es animada, espere hasta que se haya resuelto antes de revisar. El objetivo de la reunión de revisión es resolver problemas menores; Se debe llegar a un consenso sobre las cuestiones importantes de antemano.
La reunión puede aprobar el RFC, rechazarlo o requerir cambios antes de que se pueda considerar nuevamente. Los RFC aprobados se fusionarán en community / rfcs , y los RFC rechazados tendrán sus RP cerrados.
Participantes de RFC
Muchas personas están involucradas en el proceso de RFC:
Autor de RFC : uno o más miembros de la comunidad que redactan una RFC y se comprometen a defenderla durante el proceso.
Patrocinador de RFC : un mantenedor que patrocina el RFC y lo guiará a través del proceso de revisión de RFC.
comité de revisión : un grupo de mantenedores que tienen la responsabilidad de recomendar la adopción del RFC
Cualquier miembro de la comunidad puede ayudar proporcionando comentarios sobre si el RFC satisfará sus necesidades.
Patrocinadores de RFC
Un patrocinador es un encargado de mantenimiento del proyecto responsable de garantizar el mejor resultado posible del proceso RFC. Esto incluye:
- Abogando por el diseño propuesto.
- Guiar al RFC para que se adhiera a las convenciones de diseño y estilo existentes.
- Guiar al comité de revisión para que llegue a un consenso productivo.
- Si el comité de revisión solicita cambios, asegúrese de que se realicen y busque la aprobación posterior de los miembros del comité.
- Si el RFC pasa a la implementación:
- Asegurar que la implementación propuesta se adhiera al diseño.
- Coordinar con las partes apropiadas para lograr una implementación exitosa.
Comités de revisión de RFC
El comité de revisión decide por consenso si aprobar, rechazar o solicitar cambios. Son responsables de:
- Asegurarse de que se hayan tenido en cuenta los elementos sustantivos de la retroalimentación pública.
- Agregar sus notas de la reunión como comentarios al RP.
- Dar razones de sus decisiones.
La constitución de un comité de revisión puede cambiar de acuerdo con el estilo de gobernanza particular y el liderazgo de cada proyecto. Para el núcleo de TensorFlow, el comité estará formado por colaboradores del proyecto TensorFlow que tengan experiencia en el área de dominio en cuestión.
Miembros de la comunidad y el proceso de RFC
El propósito de las RFC es garantizar que la comunidad esté bien representada y atendida por los nuevos cambios en TensorFlow. Es responsabilidad de los miembros de la comunidad participar en la revisión de RFC cuando tengan interés en el resultado.
Los miembros de la comunidad que estén interesados en un RFC deben:
- Proporcione comentarios lo antes posible para permitir el tiempo adecuado para su consideración.
- Lea las RFC detenidamente antes de proporcionar comentarios.
- Sea civilizado y constructivo .
Implementando nuevas funciones
Una vez que se ha aprobado una RFC, puede comenzar la implementación.
Si está trabajando en un nuevo código para implementar un RFC:
- Asegúrese de comprender la función y el diseño aprobados en el RFC. Haga preguntas y discuta el enfoque antes de comenzar a trabajar.
- Las nuevas funciones deben incluir nuevas pruebas unitarias que verifiquen que la función funciona como se esperaba. Es una buena idea escribir estas pruebas antes de escribir el código.
- Siga la guía de estilo del código de TensorFlow
- Agregue o actualice la documentación relevante de la API. Consulte el RFC en la nueva documentación.
- Siga cualquier otra guía establecida en el archivo
CONTRIBUTING.md
en el repositorio del proyecto al que está contribuyendo. - Ejecute pruebas unitarias antes de enviar su código.
- Trabaje con el patrocinador de RFC para obtener con éxito el nuevo código.
Manteniendo el listón alto
Si bien alentamos y celebramos a todos los contribuyentes, el listón para la aceptación de RFC se mantiene intencionalmente alto. Una nueva característica puede ser rechazada o necesitar una revisión significativa en cualquiera de estas etapas:
- Conversaciones de diseño inicial en la lista de correo relevante.
- No reclutar un patrocinador.
- Objeciones críticas durante la fase de retroalimentación.
- No lograr consenso durante la revisión del diseño.
- Inquietudes planteadas durante la implementación (por ejemplo: incapacidad para lograr compatibilidad con versiones anteriores, inquietudes sobre el mantenimiento)
Si este proceso está funcionando bien, se espera que los RFC fallen en las etapas anteriores, en lugar de en las posteriores. Un RFC aprobado no es garantía de un compromiso de implementación, y la aceptación de una implementación de RFC propuesta aún está sujeta al proceso de revisión de código habitual.
Si tiene alguna pregunta sobre este proceso, no dude en preguntar en la lista de correo de desarrolladores o presentar un problema en tensorflow / community .