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

94

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?

rjzii
fuente
6060
Parece que su proyecto tiene problemas de comunicación bastante serios.
tzerb
82
¿Requiere nuevas contrataciones para revisar todo el historial de confirmaciones?
Steven Evers
3
Los nuevos empleados no deberían pasar por la base del código y cambiar las dependencias sin una dirección específica para hacerlo.
Midnotion
28
@Midnotion Entonces, ¿en algún lugar en el camino desde el nuevo empleado hasta el desarrollador principal te tomas el tiempo para revisar todo el historial de compromisos? Fascinante.
Nathan Cooper
66
Eso todavía no hace que sea una buena idea poner información crítica únicamente en el historial de confirmación.
17 de 26

Respuestas:

143

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.

17 de 26
fuente
52
De hecho, la historia de compromiso es la historia del proyecto. Al igual que sería estúpido tener información crucial en la historia de las ediciones wiki, y no en la página en sí. El historial (ya sea código o wiki) es para referencia sobre lo que sucedió anteriormente, no sobre lo que debería suceder ahora.
Ordous
48
Si es posible para el SDK ficticio, agregaría una prueba de unidad diseñada específicamente para pasar bajo V2 y fallar bajo V3 con una declaración de afirmación explícita que da la razón para no actualizar a V3. El historial de confirmación es un buen lugar para indicar por qué está haciendo ese cambio para los revisores de código, no para documentar las mejores prácticas.
Klors
3
@Klors Siempre y cuando no se limite a las definiciones más pedantes de las pruebas unitarias y se niegue a hacer otros tipos de pruebas automatizadas, una prueba basada en verificar el sistema de archivos / etc. para el nombre de las bibliotecas (si tiene la versión codificada en él) o un hash / suma de verificación del archivo en sí podría usarse para lanzar una bandera roja a cualquiera que desee actualizar la biblioteca, incluso en los casos en que la falla de las nuevas versiones es difícil / imposible de capturar en una prueba. (p. ej., condiciones de carrera multiproceso)
Dan Neely
18
@Klors Estaba pensando lo mismo, pero en mi opinión, la prueba unitaria debería demostrar la razón para usar v2 sobre v3, de esa manera si la prueba unitaria pasa con v4, no tienes una prueba unitaria que requiera v2 para no razón.
Mateo
99
Otra razón para no usar el historial de confirmación para esto: el historial de confirmación es un registro permanente. Si la razón para no actualizarse desaparece, el historial de confirmación seguirá conteniendo la advertencia de no actualizar, lo que podría ser confuso. Necesita un lugar donde las listas de requisitos como este se mantengan actualizadas, para que los desarrolladores no tengan que verificar si las cosas siguen siendo relevantes.
Jules
69

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.

Daenyth
fuente
11
Estoy de acuerdo: la mejor ubicación para la información crítica es "en tantos lugares como sea posible". Tal vez el pom.xmlarchivo de proyecto o equivalente, un archivo Léame, etc., pero el historial de confirmación sigue siendo bueno. Si estoy buscando actualizar una biblioteca, puedo verificar el historial de la versión existente para ver cuándo se actualizó, así como cualquier nota sobre los problemas que tuvo el committer. Pero no quisiera profundizar en la historia para reunir toda la documentación. Es una buena fuente suplementaria .
35

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.

Jeffery Thomas
fuente
77
Sí, el comentario debe colocarse "en la ruta" del cambio. Por lo tanto, es técnicamente imposible realizar la acción sin ver la advertencia. Se parece mucho a los controles de seguridad.
dss539
Haga clic en +1 para la sugerencia de crear una historia / boleto para la actualización en su rastreador de problemas, configúrelo en "En espera" con una explicación de por qué aún no se puede hacer. El rastreador de problemas es un lugar que realmente puede exigir a las personas que busquen antes de trabajar en algo.
Andrew Spencer
+1 Citando a Jeff Attwood (aunque habla de, ugh, "usuarios"): "La próxima vez que diseñes [X], considera la miopía [del cliente]. Te sorprenderá lo miope que pueden ser tus [clientes]. Piensa mucho en colocar las cosas directamente frente a ellas, donde no solo sean visibles, sino inevitables. De lo contrario, es posible que no se vean en absoluto ". blog.codinghorror.com/treating-user-myopia
heltonbiker
17

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.

Karl Bielefeldt
fuente
1
Esta es la única respuesta verdadera. Capturar el fallo en una prueba unitaria evita que ocurra la actualización incorrecta. Período.
Dirk Bester
15

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í.

Damon
fuente
44
+1 La palabra clave real es solo . Ciertamente no hace daño si la información se almacena en un mensaje de confirmación además de otros lugares más adecuados. Llegó al OP, ya que el registro de confirmación era la única documentación disponible.
JensG
13

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".

metal de piedra
fuente
11

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 ...

FrustratedWithFormsDesigner
fuente
44
Me gusta la idea del grupo de correo electrónico. Demasiados lugares en los que he trabajado dependen de direcciones individuales y las cosas no se transmiten a nuevos miembros.
JeffO
20
¿Qué pasa si alguien nuevo viene a tu equipo? ¿Quién es responsable de darles este tipo de conocimiento pseudoinstitucional?
ABMagil
3
@ABMagil: la información entra en un wiki. Los desarrolladores que son nuevos en el equipo generalmente comienzan allí, en algunas páginas introductorias. Luego acuden a individuos específicos (que han puesto tiempo a disposición para ayudar al nuevo desarrollador) cuando tienen preguntas específicas (y siempre lo hacen). Para nosotros, probablemente terminaría en la "Guía de configuración del desarrollador para ApplicationX", NOTE: Do not use SDK vers. x.y.z because...pero la comunicación inicial debería ser un correo electrónico.
FrustratedWithFormsDesigner
16
-1 correos electrónicos no funcionan bien como documentación
BlueRaja - Danny Pflughoeft
66
@ BlueRaja-DannyPflughoeft: el correo electrónico proporciona un método simple y fácil de usar para que todos en el equipo sepan de inmediato que se ha descubierto un problema al usar una versión específica de una biblioteca específica y que esta versión no debe usarse. Como se indicó, la documentación a largo plazo se realiza mejor en la wiki de un equipo o en algún otro tipo de base de conocimiento.
FrustratedWithFormsDesigner
5

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.

JeffO
fuente
2

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.

Cort Ammon
fuente
Esto se lee más como un comentario que como una respuesta. Ver: Cómo responder
mosquito
Buen punto, lo expandí. Esperemos que esto cumpla mejor con los criterios de StackExchange.
Cort Ammon
Creo que esta respuesta aborda mejor el tema de la pregunta. El historial de confirmación es bueno para guardar información si una persona sabe que debería estar buscando una nota. Si no hay razón para examinar la 'culpa' de una línea dada, como la inclusión de un SDK, entonces esa documentación no se leerá.
Seth Battin
1

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!

fresa
fuente
Si bien la actualización del SDK, que era un número de versión menor en lugar de mayor, fue lo que finalmente llevó a esta pregunta, esta línea de razonamiento ha estado apareciendo en el grupo por un tiempo.
rjzii
¿Por qué se habría rechazado la solicitud de extracción? ¿Cómo se supone que la persona responsable de esa decisión descubra (o recuerde) la restricción de versión?
Ben Voigt
@BenVoigt Bueno, o los líderes del equipo sabían sobre la restricción, o nadie la recordaba y esto fue redescubierto después de encontrar problemas. De cualquier manera, el uso de las solicitudes de extracción, no hay culpar al nuevo desarrollador alquiler humilde, como los adultos mayores aprobar el cambio antes de que sea permitido en.
wberry
@wberry: O un desarrollador senior diferente procesó la solicitud de extracción de la persona que sabía sobre la restricción de la versión. A menos que todos tirón solicitudes tienen que ser aprobados por todos los desarrolladores, lo que parece como un gasto dudosa de los recursos.
Ben Voigt
0

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.

JimS
fuente
0

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).

Pero P.
fuente