Revisiones de código

En este documento, se explica la filosofía de revisión de código del equipo de XLA, una filosofía que desarrollamos a lo largo de años de experiencia colectiva de trabajo en proyectos de código abierto en general y en XLA en particular.

Los diferentes proyectos de código abierto tienen diferentes expectativas culturales sobre cuánto pueden pedirles a los autores de código los revisores. En algunos proyectos, los revisores toman una solicitud de extracción (PR) "mayormente correcta", la modifican y la envían. XLA adopta un enfoque diferente: esperamos que los autores iteren en las PR hasta que estén lo suficientemente buenos como para enviarlos sin cambios adicionales.

El motivo principal de este enfoque es que queremos que los autores de RR.PP. aprendan a ser colaboradores de XLA en su totalidad. Si los revisores corrigen problemas en las solicitudes de redacción, es mucho más difícil para los autores aprender. El enfoque de XLA puede ser desafiante tanto para los revisores como para los autores, pero creemos que, en última instancia, nos ayuda a hacer crecer la comunidad.

Aprender a ser un "colaborador de XLA completo" no se trata solo de escribir código que no tenga errores. Hay mucho más para obtener información sobre cómo contribuir a XLA. Incluye lo siguiente:

  • estilo de programación
  • los casos extremos a tener en cuenta
  • expectativas respecto de la escritura de pruebas
  • expectativas sobre los comentarios y las descripciones de RR.PP.
  • expectativas en torno a la construcción de infraestructura para respaldar los cambios

A medida que aumentas el conocimiento del proyecto y la confianza de los revisores, puedes esperar menos comentarios, ya que escribes de forma natural un código más alineado con las expectativas del revisor.

Al igual que muchos proyectos de código abierto, XLA cuenta con pocas personas con mucha experiencia y muchas personas relativamente nuevas. Los que tenemos mucha experiencia tienen muchas exigencias de nuestro tiempo. Para hacer que las PR avancen de manera oportuna y reducir la cantidad de iteraciones, sigue estas sugerencias:

  • Revisa con cuidado el informe de relaciones públicas o solicita que un colega lo revise antes de enviarlo: Intenta quitar los errores triviales (estilo de código, ortografía y gramática, entre otros) antes de enviar el informe de relaciones públicas para su revisión. Asegúrate de que todas las pruebas sean exitosas.
  • Lee atentamente los comentarios del revisor: Intenta comprender qué pide el revisor y trata de abordar todos los comentarios antes de publicar una nueva versión.
  • Evita los debates tangenciales (bicicletas): Los debates técnicos y los desacuerdos son muy valiosos y nadie es perfecto. Sin embargo, evita los debates que no marcan la diferencia o que son solo estilísticos. Si no estás de acuerdo con el comentario de un revisor, intenta detallar tus razones de la manera más precisa y completa posible para evitar discusiones largas.
  • Evita hacer las "preguntas de opiniones más frecuentes" que se enumeran a continuación: Enumeramos algunas respuestas a preguntas comunes y las razones que se mencionan a continuación.

En general, te invitamos a que la revisión de tus solicitudes de respuesta tome el menor tiempo posible. Así podremos revisar los cambios rápidamente.

Gracias por contribuir a XLA. ¡Que disfrutes del hackeo!

Preguntas frecuentes sobre las opiniones

El equipo de XLA no tiene un equipo de infraestructura dedicado, por lo que depende de todos compilar bibliotecas auxiliares y evitar deudas técnicas. Consideramos que es una parte habitual de los cambios de XLA y se espera que todos participen. Por lo general, cuando escribimos código, compilamos infraestructura según sea necesario.

Los revisores de XLA pueden pedirte que crees una infraestructura (o que hagas un gran cambio en una RR.PP.) junto con una solicitud de extracción que hayas redactado. Esta solicitud puede parecer innecesaria u ortogonal para el cambio que intentas realizar. Es probable que esto se deba a una discrepancia entre tus expectativas sobre la infraestructura que necesitas desarrollar y las expectativas de tu revisor al respecto.

Está bien que las expectativas no coincidan. Esto se espera cuando eres nuevo en un proyecto (y a veces incluso nos pasa a nosotros como sombreros antiguos). Es probable que los proyectos en los que trabajaste en el pasado tengan diferentes expectativas. ¡Eso también está bien y se espera! No significa que ninguno de estos proyectos tenga un enfoque incorrecto; solo son diferentes. Te invitamos a participar en las solicitudes de infraestructura junto con todos los demás comentarios de opiniones como una oportunidad para saber lo que esperamos en este proyecto.

"¿Puedo abordar tu comentario en un próximo comunicado de prensa?"

Una pregunta frecuente con respecto a las solicitudes de infraestructura (o cualquier otra solicitud grande) en las PR es si el cambio se debe realizar o no en la solicitud de extracción original o si se puede hacer a modo de seguimiento en una PR futura.

En general, XLA no permite que los autores de las relaciones públicas aborde los comentarios de las opiniones con esas relaciones públicas de seguimiento. Cuando un revisor decide que algo debe abordarse en una RR.PP. determinada, por lo general, esperamos que los autores lo hagan en ese documento, incluso si lo que se solicita es un cambio grande. Este estándar se aplica de forma externa y también interna dentro de Google.

Hay varias razones por las que XLA adopta este enfoque.

  • Confianza: Ganarse la confianza del revisor es un componente clave. En un proyecto de código abierto, los colaboradores pueden aparecer o desaparecer cuando quieran. Una vez que aprobamos una RR.PP., los revisores no tienen forma de garantizar que se realicen las tareas de seguimiento prometidas.

  • Impacto para otros desarrolladores: Si enviaste un PR relacionado con una parte en particular de XLA, es muy probable que otras personas tengan en cuenta la misma parte. Si aceptamos una deuda técnica en tu solicitud de Relaciones Públicas, todas las personas que examinen este archivo se verán afectadas por esta deuda hasta que se envíe el seguimiento.

  • Ancho de banda de los revisores: Aplazar un cambio para realizar un seguimiento implica varios costos a los revisores que ya están sobrecargados. Es probable que los revisores olviden de qué se trataba el primer informe de relaciones públicas mientras esperan el seguimiento, lo que dificulta la próxima revisión. Además, los revisores deberán hacer un seguimiento de los seguimientos esperados para asegurarse de que realmente sucedan. Si el cambio se puede realizar de modo que sea realmente ortogonal a la solicitud de extracción original para que otro revisor pueda revisarlo, el ancho de banda sería un problema menor. Según nuestra experiencia, este no suele ser el caso.