¿Debería usarse el historial de confirmación para transmitir información crítica a los desarrolladores?

Durante una reunión sobre la reversión de un SDK de un tercero desde la última versión, se observó que nuestros desarrolladores ya señalaron en el historial de confirmación que la última versión no debería usarse.

Algunos desarrolladores argumentaron que esta era una mala práctica y que, en cambio, debería haberse anotado en el archivo fuente (es decir // Don't upgrade SDK Version x.y.z, see ticket 1234) o en un READMEarchivo de nivel de proyecto . Otros argumentaron que, dado que el historial de confirmación es parte de la documentación del proyecto, es un lugar aceptable para dicha información, ya que todos deberíamos leerla de todos modos.

¿Debería usarse el historial de confirmación para transmitir información crítica a otros desarrolladores o debería duplicarse dicha información en otra ubicación, como un proyecto READMEo comentarios en el archivo fuente relevante?

Si pensara actualizarme a una versión más nueva de un SDK de terceros, el último lugar en el que buscaría es en la historia del sistema de control de código fuente.

Si su producto está utilizando la versión 2.0 de un SDK y alguien está interesado en actualizar a 3.0, no creo que sea razonable pensar que deberían mirar hacia atrás en el tiempo en su sistema de control de fuente para descubrir que no es una buena idea.

Aquí, tenemos un wiki del equipo que tiene un puñado de páginas con información interesante que cada desarrollador lee (convenciones de codificación, cómo configurar un entorno de desarrollo para construir el producto, qué material de terceros necesita instalar, etc.). Este es el tipo de lugar que sería apropiado para una advertencia contra la actualización de una biblioteca de terceros.

Debe anotarse en el historial de confirmación, pero el mejor lugar absoluto para colocar el aviso es en el mismo lugar en el que define la dependencia. Si tiene, por ejemplo, un archivo maven .pom que declara sus dependencias de artefactos, haría algo como:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Directamente sobre tu <dependency>línea.

El problema n. ° 123 incluiría detalles sobre cómo se bloquea, la versión que actualizó que causó los bloqueos, y probablemente debería agregarse nuevamente a su cartera de pedidos para volver a visitarlo más tarde; es posible que haya una versión más nueva que solucione el problema. Ya sea automáticamente editando el ticket o manualmente, enviará un correo electrónico al equipo para informarles sobre el problema actual ahora, y al estar en el rastreador permite que las personas lo encuentren nuevamente más tarde.

La razón para ponerlo con la declaración de dependencia es porque quien quiera cambiar la versión la verá en el momento en que quiera cambiarla y entenderá por qué no debería hacerlo.

No comentaría en el código fuente porque puedo imaginar fácilmente una situación en la que alguien realiza una verificación de sus dependencias y comienza a actualizarlas. No deberían necesitar explorar la base de código para cada comentario TODO para hacer eso.

La vinculación al ticket de problema le permite a un desarrollador curioso saber cómo falló y potencialmente volver a visitarlo más tarde. Sin eso, podría volverse bastante estático y nunca volver a actualizarse.

Las piezas de información críticas y no intuitivas deben documentarse hacia dónde buscarán las personas cuando consideren la información.

Para los equipos y proyectos en los que he trabajado, cometería el retroceso con el comentario sobre por qué falló la nueva versión. Agregaría una historia de retraso para volver a intentar la actualización si la nueva versión se soluciona. Agregaría comentarios al sistema de compilación / scripts de compilación donde la biblioteca está vinculada.

La reversión proporcionará a los futuros desarrolladores un contexto cuando analicen la historia del proyecto. La historia de la cartera de pedidos mantiene la necesidad de esta actualización como parte activa del proyecto. Los comentarios del sistema de compilación están justo donde los cambios tendrán que estar cuando la biblioteca finalmente se actualice.

No lo comentaría en el código y no lo agregaría a un archivo README. Los desarrolladores que estén pensando en probar la actualización no verán estas piezas. Si lo agrega allí, cuando el problema con la biblioteca finalmente se solucione y se realice una actualización, deberá eliminarlo. Este paso a menudo se olvida: resulta en notas que son contraproducentes para el proyecto.

Si su proyecto tiene una configuración diferente o un flujo diferente, entonces su respuesta puede ser diferente. Creo que la clave es poner la información correcta donde el desarrollador la verá al hacer el trabajo para la actualización. De esa manera, si no es el momento adecuado para la actualización, el desarrollador lo verá y se detendrá, y cuando sea el momento adecuado, lo verá y eliminará la nota para no confundir a los futuros desarrolladores.

Quería prestar más atención al comentario de Matthew destacando su importante idea en una respuesta. Hay una razón por la que no desea actualizar su SDK, y esa razón debe ser capturada en una prueba unitaria. No es un cheque para un número de revisión, sino la razón subyacente real.

Por ejemplo, supongamos que hay un error en la nueva versión. Escriba una prueba unitaria que verifique ese error. Si luego corrigen ese error en el SDK, la actualización se realizará sin problemas. Si hay un cambio de API incompatible, escriba una prueba que verifique que su código sea compatible con la nueva API o que el SDK sea compatible con la antigua API. Eso es más una prueba de integración que una prueba unitaria, pero aún debería ser factible.

Mi empresa genera más de 50 confirmaciones por día, y no somos exactamente enormes. Incluso si todos los desarrolladores leen cada mensaje de confirmación, lo que seamos sinceros, la razón por la que necesitamos un historial de confirmación grabado es porque la gente no puede recordarlo. Y las personas no regresan y leen la historia más tarde a menos que haya un problema. Y no tienen ninguna razón para sospechar un problema en una actualización que, hasta donde saben, aún no ha ocurrido.

Envíe un correo electrónico para evitar la duplicación de trabajo a corto plazo y anótelo en sus scripts de compilación y un archivo README o errata. Sin embargo, especialmente si el problema con la nueva versión es sutil y lleva mucho tiempo solucionarlo, necesita una forma de hacerlo obvio. Eso significa una prueba unitaria.

Estoy reformulando la pregunta como "¿Debería comunicar información crítica que descubro al resto del equipo solo a través de un mensaje de confirmación?" Porque creo que eso hace obvio que no, no deberías. Intento comunicarme mucho (esto es algo en lo que la mayoría de los equipos de desarrollo, en mi experiencia, necesitan hacer un esfuerzo activo) y ciertamente hago todo lo posible para evitar crear trampas o dejar que mientan.

Si la cadena de acciones que me llevó a tal descubrimiento fue activada por un boleto, actualizaría el boleto (y me aseguraría de que las personas que deberían saber esto tengan visibilidad), probablemente lo mencionaría cara a cara (esperando al menos dejar a alguien con una sensación persistente de que "Gee, creo que Damon dijo algo sobre actualizar eso"), y por supuesto dejaría un comentario en el código en el momento en que se incluyó el SDK para que nadie pueda actualizar sin tener la oportunidad de verlo. Podría ver si también podría incluirlo en algún lugar de nuestro wiki de desarrollo, aunque eso se hace más con miras a las futuras contrataciones, no al equipo actual.

Solo toma un par de minutos más en comparación con el tiempo que probablemente tomó encontrar y descubrir el problema. Ciertamente, no decidiría cuál de los documentos menos utilizados y de baja señal de nuestra documentación y lo dejaría así.

Debe estar en el historial de confirmaciones, pero no solo en el historial de confirmaciones, imagine por un momento que contrata a un nuevo desarrollador. ¿Espera que el nuevo desarrollador lea todos los mensajes de compromiso de los últimos 10 años de su proyecto porque algunos de ellos serán críticos para comprender su base de código?

En segundo lugar, la situación, pero no los cambios en el código, ¿va a realizar confirmaciones de "documentación" para que pueda agregar mensajes de confirmación en la línea de "el mensaje de confirmación de la revisión 5432 ahora es incorrecto, aquí está la situación actual".

No estoy seguro de cómo se comunica su equipo, pero creo que la forma más efectiva de decir esto es enviar primero un correo electrónico al grupo de correo electrónico del equipo, marcado como "URGENTE" con el cuerpo diciendo

Chicos, no podemos usar SDK v xyz porque hace que el búfer Foo se desborde y el servicio Bar se bloquee. Seguir con la versión xyy

Eso es lo que hemos hecho aquí y es la forma más confiable de transmitir el mensaje. Si realmente quiere ser quisquilloso (y si su sistema de correo electrónico lo permite), solicite un "recibo de lectura" en el correo electrónico.

Una vez que le haya contado a todo el equipo, se debe incluir documentación más detallada en una wiki del equipo. Esto variará, dependiendo de cómo estructura su documentación. Si tiene una sección específica para las dependencias y requisitos de sus aplicaciones, sería un buen lugar para agregarla.

Un lugar adicional para documentar este tipo de problema podría estar en el código fuente, aunque eso no siempre funciona. Si SDK version ...solo se hace referencia en uno o dos lugares obvios, puede incluir una nota sobre no actualizar.

El historial de archivos en el control de origen puede ser muy largo y, según los desarrolladores, podría tener varias entradas por día. Alguien que ha estado de vacaciones durante una semana podría no tener tiempo para leer el historial de compromisos de una semana. El archivo README es un lugar mejor, ya que es un poco más central y las personas pueden estar más inclinadas a leerlo, pero no puede asegurarse de que todos realmente lean el archivo README. Bueno, supongo que podrían hacerlo si ven que ha cambiado ...

Algo así debería haberse incluido en los comentarios de confirmación, pero también se beneficiará de estar en otros lugares.

Quien toma la decisión de actualizar, necesita tener los hechos. Esa persona puede no vivir en el control de la fuente. ¿Qué pasaría si alguien hubiera leído sobre este problema en SO y nunca lo hubiera puesto en la base del código?

Es necesario que haya algún tipo de documento sobre este SDK de terceros.

• ¿Qué problema soluciona?
• ¿Por qué fue elegido este en particular?
• Qué consideraciones deben hacerse en cuanto a: versiones, actualizaciones, pruebas, etc.
• ¿Quién toma esta decisión?

Tiene un caso en el que algo como esto se abrió paso en el control de versiones, y debe recomendar que todos usen esta información tanto como sea posible. Solo su equipo puede decidir dónde buscará alguien en cualquier documentación, control de fuente o rastreador de errores para obtener la mayor cantidad de información posible sobre el tema. De lo contrario, se olvidará, alguien lo hará de todos modos, y tendrá suerte si activa la memoria de alguien y rápidamente lo revierte.

La historia es un gran lugar para colocar datos destinados a un lector que los busca conscientemente y tiene un sentido general de dónde debería estar. Es un lugar muy malo para colocar datos que deben ofrecerse a un usuario, en lugar de buscarse.

Las historias son cuerpos muy grandes de texto relativamente sin clasificar. Por lo general, están destinados a proporcionar a un desarrollador información detallada sobre lo que cambió y por qué se modificó. Esto puede ser una sobrecarga de información a menos que uno sepa lo que está buscando.

Si un usuario no sabe lo que está buscando, entonces la información se oculta rápidamente bajo cientos de registros de confirmación, y no tiene ninguna herramienta para podar la pila de información frente a ellos.

Interpreto que esta situación tiene dos problemas básicos, posiblemente tres.

• Una actualización de SDK no deseada llegó a la fuente, donde podría afectar negativamente al producto.
• De la pregunta: el colaborador que realizó la actualización no deseada no sabía sobre una decisión previa específica de no actualizar.

El primero de ellos, en mi opinión, es el más serio. Si una actualización de SDK no deseada puede ingresar al código, también pueden ocurrir otros problemas.

Alguien sugirió agregar un caso de prueba de unidad que fallará si detecta la actualización. Si bien evitaría que ocurriera la actualización, creo que este es un camino peligroso, que conduce al flujo de lava con el tiempo. Parece inevitable que en algún momento en el futuro se actualice el SDK, para incorporar nuevas funciones o correcciones de errores, o porque la versión anterior ya no es compatible. Imagine el rascarse la cabeza, tal vez incluso los argumentos, que ocurrirán cuando dicha prueba unitaria falle.

Creo que la solución más general es ajustar el proceso de desarrollo. Para git, use el proceso de solicitud de extracción . Para Subversion y herramientas anteriores, use ramas y diff. Pero tenga algún proceso que permita a los desarrolladores senior detectar este tipo de problemas antes de que entren en la base de código y afecten a otros desarrolladores.

Si el proceso de solicitud de extracción se hubiera utilizado en su situación, y si cada solicitud de extracción es estrecha y específica, no se habría perdido mucho tiempo. Se habría enviado una solicitud de extracción para actualizar el SDK, y se rechazó comentando que no se desea la actualización. Nadie más habría sido afectado, y no habría necesidad de revertir la actualización del SDK.

Pero para responder directamente a la pregunta original, estoy de acuerdo con otros en que esperar que todos los desarrolladores lean completamente el historial de revisiones completo del código, las notas de la versión, etc. para avisos como este es una pérdida de tiempo valioso. ¿Qué tiene de malo un correo electrónico breve del equipo?

Posible tercer problema: ¿Por qué no se desea la actualización en primer lugar? Claramente, al menos un desarrollador pensó que la actualización sería algo bueno. Hay muchas buenas razones para retrasar una actualización, pero también muchas malas. ¡Tenga cuidado de evitar el flujo de lava (código innecesario de compatibilidad con versiones anteriores) y el culto a la carga ("no podemos actualizar eso, pero no sé por qué") antipatrones!

Yo diría que agregar ese tipo de información a un historial de confirmación está bien, pero aún debe documentarse correctamente. Recientemente comenzamos a usar la confluencia (por atlassian). Se puede buscar, puede establecer ciertas páginas como favoritas, etc.

Algunas otras herramientas pueden ser un cuaderno público en evernote o google docs.

Ampliando la respuesta de Karl , seguiría un enfoque que aplica automáticamente la restricción como parte del proceso de registro en sí. Necesita algo que no requiera ninguna acción proactiva en nombre del desarrollador, como leer un documento / wiki / README, y que no se pueda anular de forma encubierta.

En la tierra de control de fuente TFS puede codificar políticas de registro personalizadas que ejecutan reglas en el registro. Por ejemplo, podría definir una política que evalúe la versión en un archivo de configuración con un registro pendiente y fallará si no es igual a xyz. Estas reglas realmente evitan que el desarrollador realice el registro y puede proporcionar un mensaje descriptivo. Las políticas pueden anularse, pero es posible generar alertas cuando esto sucede.

Una alternativa podría ser el check-in cerrado que fallará con alguna forma de prueba unitaria que evalúe directa o indirectamente la versión del SDK, como Karl mencionó.

Aprecio que esta respuesta esté muy centrada en TFS, pero posiblemente existan características similares en los sistemas de control de versiones / CI que se aplican en su situación (si no es TFS).