La revisión de código puede ser mejor

• Muchos desarrolladores sienten una gran insatisfacción con la experiencia de revisión de código en GitHub, y se están probando nuevos enfoques para mejorarla
• Una herramienta experimental llamada git-review fue diseñada para manejar la revisión de código directamente en local junto con el código, en lugar de usar una interfaz web en el navegador
• La revisión se gestiona como un único commit, dejando comentarios de revisión como si fueran anotaciones dentro del código, y tanto el revisor como el autor van editando ese commit en conjunto
• Sin embargo, cuando el código se modifica o se hace rebase durante la revisión, surgen incomodidades con el manejo de conflictos y el uso de --force-with-lease, por lo que no logró un gran éxito
• Al final se volvió a la revisión basada en web, pero la idea de incluir directamente el estado de la revisión dentro del repositorio sigue siendo atractiva, y con futuras mejoras en Git, como la adopción de un Change-Id al estilo Gerrit, podría aparecer una alternativa mejor

---

Reconocimiento de los problemas en los sistemas de revisión de código

• Actualmente muchas personas están inconformes con el proceso de revisión de código de GitHub
• Los problemas principales incluyen la falta de soporte para pull requests apilados y revisión interdiff, además de que
  • el estado de la revisión no se guarda dentro del repositorio
  • la revisión depende obligatoriamente de una interfaz web remota y priorizada
• Los problemas que yo veo son la falta de descentralización de la revisión y la ineficiencia de la interfaz

Comparación del flujo de trabajo de escritura de código y revisión

• Cuando escriben código, las personas usan un editor en local
  • hay poca latencia de memoria y NVMe, y es un entorno optimizado para los flujos de trabajo particulares de cada usuario
• Para revisar código, también se prefiere trabajar haciendo pull local de la rama fuente
  • con herramientas como Magit es posible explorar no solo el diff, sino también todo el contexto del código
  • se puede aprovechar un entorno de desarrollo potente para ejecutar pruebas, saltar a definiciones o intentar refactorizaciones
• En cambio, para dejar feedback en un PR hay que ir al navegador y usar una interfaz web lenta, y en diffs grandes incluso hay bastante retraso al escribir

Interfaz ideal de revisión de código y estructura de almacenamiento

• En la práctica, lo más natural es dejar comentarios inline en el código o incluso modificar directamente el código

  // CR(matklad): Hm, this check seems imprecise to me.  
  // Shouldn't we compare `replica.view` instead of `header.view` here?  
  if (header.view != view) return;  
  

• Como los datos se almacenan en una base de datos remota y no en el repositorio local de git, también aparecen problemas de latencia y vendor lock-in

La idea de git-review y la experiencia real

• La idea de git-review es la siguiente:
  • la revisión de código se realiza en un único commit en la parte superior de la rama del PR
  • a ese commit se le agregan comentarios en el código con marcadores especiales
  • el revisor y el autor van editando ese commit por turnos, colaborando sobre la base de push --force-with-lease
  • cuando todos los comentarios quedan marcados como resueltos (//? resolved), se agrega un commit de revert al cerrar la revisión, para dejar el registro
• La idea es simple y práctica, pero en la realidad aparecieron varios problemas
  • cuando se modifica el código durante la revisión, los conflictos con los comentarios son frecuentes en commits inferiores o en commits nuevos
  • el proceso de force-push genera fricción en la colaboración y aumenta la complejidad del trabajo
  • se vuelve difícil manejar la desalineación entre el historial de cambios del código y el avance de la revisión, así como los conflictos de merge

Nuevos cambios y posibilidades futuras

• A futuro existe la posibilidad de que Git upstream adopte un Change-Id al estilo Gerrit
  • eso facilitaría el seguimiento del historial de cambios por commit y ampliaría el soporte para la revisión interdiff
  • pero se espera cierto choque con el enfoque de git-review
  • con una nueva estructura de Change-Id podrían ser posibles enfoques distintos, como agregar comentarios de revisión directamente al commit

Conclusión y presentación de sistemas de referencia

• Por ahora, al final se volvió de nuevo a la revisión de código basada en interfaz web
• La necesidad de una solución mejor sigue vigente
• Presentación de sistemas y herramientas relacionadas que vale la pena revisar
  • Fossil: sistema SCM que guarda toda la información dentro del repositorio
  • NoteDb: integra en git el historial de almacenamiento del estado de revisión de Gerrit
  • git-bug: guarda la información de issues en git
  • git-appraise: conserva la información de revisión dentro del propio git
  • prr: implementa una interfaz de revisión dentro del editor conectándose con la API de GitHub
  • How Jane Street Does Code Review: presenta un ejemplo de una realidad mejor
  • git-pr: proyecto que reemplaza todo el flujo de trabajo de PR con funciones nativas de git

Cierre

• Todavía no existe una solución perfecta, y continúan los intentos por lograr una mejor experiencia para desarrolladores
• Hay mucha expectativa sobre la dirección futura de esta evolución

[roxie]

No sé si el enfoque de git-review sea bueno, pero sí coincido en que las revisiones de PR basadas en GitHub son terribles..

[GN⁺]

Opinión de Hacker News

• Algo que me ha frustrado durante mucho tiempo en las revisiones de código es que el feedback realmente útil —más allá de observaciones triviales de estilo o preferencia— casi siempre llega demasiado tarde. A veces, el único resultado (o uno de los pocos) de la revisión es: "esto hay que rehacerlo completo con un diseño nuevo" o "en realidad nunca debimos hacer este trabajo". Da la impresión de que la revisión de código es el único momento en que todos los involucrados participan de verdad y se ponen a pensar seriamente sobre el cambio. Tal vez hubo alguna discusión en una reunión o en un ticket de Jira, pero muchas veces alguien de otro equipo o área se entera de este cambio recién cuando le llega la notificación de la revisión de código. A mí también me pasa seguido que me entero por esa notificación de que otro equipo implementó algo raro. No es realista esperar que todo el mundo haga seguimiento previo de todo. En la universidad, en los 90, hacíamos revisiones de diseño, pero nunca vi algo así en el trabajo real. Y tampoco creo que una revisión de diseño garantice que se detecten todos los problemas de antemano.

  • En el mundo de la ingeniería de software hay muy poca ingeniería real. También pasa que la industria no tolera bien la lentitud de un proceso de ingeniería de verdad. La mayor parte del software no es crítico para la vida, y los bugs o errores se pueden arreglar después. Los riesgos y la posibilidad de parchear después son muy distintos a los de puentes, fábricas o motores de avión, donde fallar no es aceptable.

  • Nuestro equipo es un grupo pequeño de 4 a 6 desarrolladores. Cuando alguien ya tiene un borrador mental de una funcionalidad nueva, lo conversa enseguida con sus colegas. Como todos trabajamos así, la revisión de código se enfoca en cosas menores como code smells, y la arquitectura general normalmente la deciden 2 o 3 personas por adelantado. Si el equipo no está de acuerdo con el código, la gente empieza a no querer tocar el código de los demás y la situación se deteriora. Creo que incluso a mayor escala esto puede funcionar bien si la responsabilidad se comparte de forma adecuada.

  • Que todos los involucrados participen solo en el momento de la revisión de código no es un problema de Git ni del sistema de control de versiones, sino de la organización. El problema es no poder compartir el contexto de por qué se creó el PR, la discusión del ticket y el proceso de toma de decisiones. Es un ejemplo de una organización disfuncional: sería como criticar el proceso editorial porque todos recién se involucran en serio cuando el libro ya salió impreso.

  • En nuestra organización siempre exigimos un RFC para decisiones de diseño fundamentales. Qué cuenta como una decisión de diseño fundamental se define de forma autónoma dentro del equipo según el caso. Si en la etapa de epic en Jira todavía no está claro cómo se va a implementar algo en detalle, primero se asigna la redacción de un RFC. El RFC puede ser solo para nuestro equipo o para todo el equipo de software; en este último caso, todos pueden leerlo y dejar comentarios antes de la reunión que se hace cada dos semanas. Aunque cueste trabajo, es muchísimo mejor que trabajar sin un proceso colaborativo de diseño basado en RFC.

  • Por mi experiencia, coincido con el tema de las revisiones de diseño. Antes hacíamos documentos formales de diseño y revisiones, pero después cambiamos a prototipado y diseño iterativo. En la etapa de diseño muchas veces se nos escapaban detalles importantes, y como ya habíamos invertido mucho tiempo, después se tendía a pasarlos por alto. También era poco eficiente reunir a todo el equipo para revisar, así que al final los problemas terminaban apareciendo en la revisión de código. Además, hay mucha gente que no sabe escribir buenos documentos de diseño o no tiene motivación para hacerlo. En la práctica, con más de 5 personas, este tipo de ineficiencia parece inevitable. Un entorno ideal sería uno con el PO, los usuarios principales y unos 5 desarrolladores.

• Me pareció muy interesante ver una publicación en HN sobre stacked pull request. Cuando empezamos graphite.dev, mucha gente que no venía de Facebook o Google ni siquiera conocía este flujo. Es interesante ver lo rápido que están cambiando las tendencias de revisión de código en apenas 3 o 4 años.

  • Como usuario de arcanist desde antes de Mercurial, sigo recomendando activamente Graphite a equipos que todavía sufren con PRs enormes, merge commits y demás. Me impresionan mucho tanto la audacia como el resultado de haber logrado integrarlo con PRs. Me gustaría que Graphite tuviera un modo prescriptivo que inicializara el repo con una configuración más hardcore para poder asumir reglas más fuertes.

  • Aunque Graphite es una solución muy buena, también es bastante caro y es difícil convencer a quienes toman decisiones de compra. Ojalá una herramienta tan buena como Graphite se vuelva open source o termine integrada en GitHub.

  • A veces extraño el workflow de fig

  • Después del incidente de seguridad reciente en CodeRabbit, me cuesta animarme a probar herramientas nuevas que integran LLMs con el codebase. Es muy fácil que un experimento novedoso termine convirtiéndose en un problema de seguridad.

  • Los stacked pull request, en esencia, agregan una complejidad que podría no existir. Hacer cambios pequeños y frecuentes es una práctica de desarrollo mucho mejor. trunk-based development o continuous integration encajan muy bien con ese objetivo.

• Cada vez más desarrolladores parecen coincidir en "cómo debería verse una herramienta de revisión". Ahora el punto importante es qué organización y qué actores pueden hacer eso viable en la práctica y sostenible en el tiempo. La adopción reciente de git change-id es un avance positivo (gracias a jj, git butler, gerrit, etc.). Graphite y GitHub se concentran en soluciones para sus propios usuarios, así que no van realmente en una dirección abierta para todos. Y las muchas herramientas de línea de comandos basadas en cliente tampoco tienen tanto impacto. Lo que de verdad hace falta es:

  • que se pueda usar completamente en local
  • soporte oficial del equipo core para vscode (aunque la integración de vscode por sí sola ya tenga un buen UX)
  • reutilizar al máximo los componentes de UI también en interfaces web como vscode web y en otros editores
  • ofrecer funciones centrales desde la CLI o como librería, con límites claros para extensiones
  • soportar commit/branch/stacked commit/agent snapshot/revisión propia del desarrollador
  • integrar de forma nativa las señales de CI/CD y construir sobre el gran trabajo de UI que mostró Meta
  • ser muy granular según el contexto y permitir cambios en cada etapa (por ejemplo, en Cursor se puede aceptar una sola línea; la revisión humana también necesita ese nivel de edición granular)
  • ser completamente incremental y ofrecer una forma sencilla de revisar solo los cambios modificados en vez de revisar todo el PR cada vez

• Mi mayor queja con GitHub es que la app es demasiado lenta. Tan lenta que de verdad hay pestañas del navegador que se congelan. Azure DevOps ha sido, por mucho, la mejor herramienta de revisión de código que he usado.

  • Cuando desarrollaba .NET en un entorno de Microsoft usé Azure DevOps, y la verdad es una herramienta que encaja muy bien con el ecosistema .NET

  • Me pregunto si has usado GitLab a fondo. De los big 4, es el que más me gusta.

  • Me da curiosidad qué fue lo que te gustó tanto de DevOps. Lo uso todos los días, pero me parece bastante similar a GitHub. Incluso a veces extraño la función de aplicar automáticamente cambios sugeridos que tiene GitHub.

  • El uso masivo de JavaScript junto con la presión por lanzar rápido crea este entorno tan lento. Aun así, sigue siendo mejor que Atlassian

• La idea de usar git directamente para la revisión de código me resulta atractiva. Es cómodo poder manipular los cambios directamente en local. No entiendo por qué habría que forzar que la revisión se limite a un solo commit; también me parece interesante un enfoque donde el revisor haga commits directamente en la rama del PR con sus comentarios o correcciones. Es una especie de híbrido entre el github flow tradicional y el flujo de mailing list + parches de Linux.

  • ¿Los PR de GitHub son de solo lectura? He visto a gente del equipo proponer cambios directamente con comentarios de "suggestion" y aplicarlos al commit con un solo clic.

  • Es raro que el commit de revisión tenga que ser uno solo. Si revisan varias personas, también aparecen problemas de edición concurrente, y además no encaja bien con el código. Lo natural sería que cada quien trabajara su revisión por separado en su propia rama, y al final hacer squash & rebase. Si la discusión se alarga, hasta se podrían ir encadenando comment commits entre sí. Lo importante es que esos datos queden guardados en algún lugar fuera de la rama main

• Cuando reviso código, prefiero traerlo a una rama local y hacer soft-reset para verlo como si yo lo hubiera escrito. Si los commits no están bien divididos, entonces cada colaborador tiene que separarlos por su cuenta para revisar, y eso es ineficiente. Si lo que se revisa es demasiado grande, es difícil decir que alguien realmente lo entendió por completo. El todo no es simplemente la suma de las partes.

  • Comparto un ejemplo de función de shell sencilla para revisar código. Con un árbol limpio, hace checkout de una rama review preconfigurada, abre el diff en nvim y al terminar limpia la rama automáticamente

  • Saber hacer buenos commits y PRs a partir de ellos es una habilidad tan importante como escribir buen código. Pero en la práctica hay más desarrolladores de los que uno pensaría que son débiles para partir PRs, escribir mensajes de commit, etc.

  • En un equipo de ciencia de datos que trabaja en paralelo, usamos 2 o 3 ramas checkout para revisión de código

  • Para revisar PRs uso https://github.com/sindrets/diffview.nvim en Neovim. Tiene una UI parecida al diff de vscode, pero aprovechando el modo diff de vim. Para revisiones ligeras, git log -p --function-context también sirve mucho

• Me interesa la idea de que una persona escriba el primer draft y otra lo pula y haga el merge. ¿Alguien lo ha probado en la práctica?

  • Estoy de acuerdo con un estilo donde más del 90% del trabajo de programación lo hace una sola persona, pero el revisor se encarga directamente de la integración final y del merge. En un trabajo anterior, el revisor siempre era quien hacía el merge, y si el cambio era grande, solo dejaba comentarios. Es muchísimo más eficiente que andar pidiéndole a alguien que haga clic en aprobar cada vez.

  • Cuando participas directamente en escribir el código que revisas, siento que puedes dar un feedback mucho más profundo. Esta estructura ayuda a que se vea como "nuestro código" y no "mi código / tu código". Va muy bien con culturas iterativas y colaborativas como TDD.

  • Este enfoque se parece a la programación en pareja asíncrona

  • Conozco gente que usa pair programming dentro de trunk-based development. Programan entre dos, y si todo está bien, hacen merge directo a main; si pasan las pruebas, despliegan de inmediato. En la práctica funciona muy bien.

• Uso la extensión de GitHub Pull Request en VSCode para revisar en local y es bastante cómoda. Puedes comentar y revisar directamente desde el editor.

  • En la web de GitHub, cuando hay muchos archivos cambiados, algunos se ocultan, pero en VSCode puedes navegar libremente y la experiencia es mucho más cómoda. Como esta función ya existe en la combinación VSCode/GitHub, supongo que también podría extenderse a otros editores

  • Sí está mejorando, pero sigue habiendo un fuerte vendor lock-in entre GitHub y VSCode

  • Abrir un PR en la web de GitHub y presionar la tecla “.” para revisar directamente en VSCode web también es una experiencia mucho mejor

• ¡Me da muchísimo gusto escuchar que Git va a tener change ID como first class! Se parece al seguimiento de revisiones de diffs en Phabricator de Facebook. Me gustaría ver algún enlace para investigarlo con más detalle

  • El problema de fondo es que git no maneja bien la información de ramas. Fossil sí recuerda en qué rama se creó cada commit. La task branch en sí misma cumple el papel de change ID. Claro, git también tiene que permitir reescritura del historial, así que no es un problema fácil de resolver

• También quiero mencionar Sourcehut. Retoma el flujo clásico de parches, issues, bugs y discusión por correo, y se integra con mailing list y CI. Drew Devault también ofrece recursos sobre cómo enviar y recibir parches en git-send-email.io y git-am.io