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

Si me gustaría ver la actualización a una versión más nueva de un SDK de terceros, el último lugar que buscaría es en el historial del sistema de control de origen.

Si su producto está usando 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 un 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 compilar el producto, qué cosas 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.

Se debe tener en cuenta en el historial de confirmación, pero el mejor lugar para colocar el aviso es en el mismo lugar donde define la dependencia. Si tiene, por ejemplo, un archivo .pom de maven que declare las dependencias de sus 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 línea <dependency> .

El problema # 123 incluiría detalles sobre cómo se bloquea, la versión que actualizó para que causó los bloqueos, y probablemente debería agregarse a su backlog nuevamente para volver a visitarlo más tarde. Es posible que haya una versión más nueva que corrija la cuestión. Automáticamente, al editar el ticket, o manualmente, enviará un correo electrónico al equipo para informarles sobre el problema actual ahora, y al estar en el rastreador, le permitirá a las personas encontrarlo más tarde.

El motivo para ponerlo junto con la declaración de dependencia es que quien quiera cambiar la versión la verá en el momento 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 ejecuta una verificación de sus dependencias y comienza a actualizarlas. No deberían necesitar revisar la base de código para cada comentario TODO para hacer eso.

Al enlazar con el ticket del problema, un desarrollador curioso puede saber cómo falló y posiblemente volver a visitarlo más tarde. Sin eso, podría volverse bastante estático y no volver a actualizarse.

Se debe documentar información crítica y no intuitiva donde las personas estarán buscando al considerar la información.

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

El retroceso proporcionará a los futuros desarrolladores un contexto al analizar el historial del proyecto. La historia del trabajo pendiente 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 deberán estar cuando la biblioteca se actualice finalmente.

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 estarán mirando 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: lo que 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 corregir la información donde el desarrollador la verá cuando haga 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, el desarrollador lo verá y eliminará la nota para que no confunda a los futuros desarrolladores.

Quería dar el comentario de Matthew más atención al resaltar su idea importante 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 de unidad. No es un cheque para un número de revisión, sino el motivo subyacente real.

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

Mi empresa genera más de 50 confirmaciones por día, y no somos exactamente grandes. Incluso si todos los desarrolladores leen cada uno de los mensajes de confirmación, seamos francos, no todos, la razón por la que necesitamos un historial de confirmación registrado es porque la gente no puede recordarlo. Y las personas no vuelven 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, por lo que saben, aún no ha ocurrido.

Por supuesto, envíe un correo electrónico para evitar la duplicación del trabajo en el 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 requiere mucho tiempo para solucionarlo, necesita una forma de hacerlo obvio. Eso significa una prueba de unidad.

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

Si la cadena de acciones que me condujeron a tal descubrimiento fuera provocada por un ticket, actualizaría el ticket (y me aseguraría de que las personas que deberían saberlo tengan visibilidad), probablemente lo mencionaría cara a cara. cara (con la esperanza de al menos dejar a alguien con una sensación molesta de que "Caramba, creo que Damon dijo algo sobre la actualización de eso"), y por supuesto, dejaría un comentario en el código en el momento en que se incluyó el SDK para que nadie Posiblemente podría actualizarlo sin tener la oportunidad de verlo. También podría ver si podría atascarlo en algún lugar de nuestra wiki de desarrollo, aunque eso se hace más con miras a futuros empleados, no al equipo actual.

Solo toma un par de minutos más en comparación con el tiempo que probablemente tardó en encontrar y descubrir el problema. Ciertamente, no decidiría esa de las piezas de baja señal de nuestra documentación menos utilizadas y dejarlo así.

Debería estar en el historial de compromiso, pero no solo debería estar en el historial de compromiso, imagínese por un momento que contrata a un nuevo desarrollador. ¿Espera que el nuevo desarrollador lea todos los mensajes de confirmación durante 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, diga la situación, pero no los cambios de 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 manera más efectiva de decir esto es primero enviar 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 x.y.z porque hace que el búfer de Foo se desborde y el servicio Bar se bloqueará. Quédate con la versión x.y.y

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 dicho a todo el equipo, se debe colocar documentación más detallada en una wiki del equipo. Esto variará, dependiendo de cómo estructure su documentación. Si tiene una sección específica para sus aplicaciones Dependencias y requisitos, sería un buen lugar para agregarla.

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

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. Es posible que alguien que haya estado de vacaciones por una semana no tenga 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 la gente podría estar más inclinada a leerlo, pero no puede asegurarse de que todos realmente lean el README. Bueno, supongo que podrían 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.

Quienquiera que tome la decisión de actualizar, necesita tener los hechos. Esa persona no puede 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 el código base?

Debe haber algún tipo de documento sobre este SDK de terceros.

• ¿Qué problema resuelve?
• ¿Por qué se eligió 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ó camino en el control de versiones, y debería recomendar a todos que usen esta información tanto como sea posible. Solo su equipo puede decidir dónde alguien va a realizar una búsqueda en cualquier documentación, control de fuente o rastreador de errores para obtener la mayor información posible sobre el tema. De lo contrario, lo olvidarás, alguien lo hará de todos modos, y tendrás suerte si trota la memoria de alguien y te lo devuelve rápidamente.

La historia es un excelente lugar para colocar datos destinados a un lector que la busca conscientemente y tiene una idea general de dónde debería estar. Es un muy mal lugar para colocar los datos que se deben ofrecer a un usuario, en lugar de buscarlos.

Las historias son cuerpos muy grandes de texto relativamente sin clasificar. Por lo general, están destinadas a proporcionar al desarrollador información detallada sobre qué ha cambiado y por qué se ha cambiado. 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, la información se oculta rápidamente en cientos de registros de confirmación y no tiene ninguna herramienta para eliminar la cantidad de información que se encuentra frente a ellos.

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

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

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

Alguien sugirió agregar un caso de prueba de unidad que fallará si detecta la actualización. Si bien evitaría que se produjera la actualización, creo que esta es una ruta peligrosa, lo que lleva a flujo de lava sobre hora. Parece inevitable que, en algún momento en el futuro, el SDK se actualice para incorporar nuevas funciones o correcciones de errores, o porque la versión anterior ya no es compatible. Imagine el rasguño de cabeza, tal vez incluso los argumentos, que se producirán cuando una prueba de unidad de este tipo falla.

Creo que la solución más general es ajustar el proceso de desarrollo. Para git, use el proceso de solicitud . Para Subversion y herramientas anteriores, use sucursales y dif. Pero tenga un proceso de algunos que permita a los desarrolladores senior detectar este tipo de problemas antes que ingresen en el código base 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 fuera estrecha y específica, no se habría desperdiciado mucho tiempo. Se habría enviado una solicitud de extracción para actualizar el SDK y se habría rechazado con el comentario de que no se desea la actualización. Nadie más se habría visto afectado, y ahora 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 revisión del código, las notas de la versión, etc. Para avisos como este es una pérdida de tiempo valioso. ¿Qué pasa con un correo electrónico corto 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 (innecesario código de compatibilidad con versiones anteriores) y cargo sect ("no podemos actualizar eso, pero no sé por qué ") anti-patrones!

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 confluencia (por atlassian). Se puede buscar, puedes configurar ciertas páginas como favoritas, etc.

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

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

En el control de código fuente de TFS puede codificar políticas de registro personalizadas que ejecutan las reglas en el momento del 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 x.y.z. Estas reglas realmente impiden que el desarrollador realice el registro y puede proporcionar un mensaje descriptivo. Las políticas pueden ser anuladas, pero es posible generar alertas cuando esto sucede.

Una alternativa podría ser los controles de acceso que fallan con algún tipo 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 versión / CI que se aplican en su situación (si no es TFS).