deployment language-agnostic release-notes

deployment - ¿Cómo se deben escribir las notas de la versión?



language-agnostic release-notes (6)

¿Hay algún tipo de directrices o mejores prácticas sobre cómo deben escribirse las notas de la versión? Creo que estoy tratando de encontrar el equilibrio adecuado entre hacer el punto sin ser demasiado específico. Además, ¿el desarrollador suele proporcionar un número de notas de lanzamiento mucho mayor para el equipo de control de calidad que el que se envía a la vista del público?

Echaré un vistazo a las notas de lanzamiento de los populares proyectos F / OSS:

Todos estos proyectos tienen notas de lanzamiento bastante legibles y equilibradas.

El principal colaborador de Release Notes sería su equipo de desarrollo. Es una buena práctica permitir que sus desarrolladores y probadores capturen cualquier información relacionada con notas de la versión en relación con sus artículos de trabajo que están vinculados a conjuntos de cambios en TFS.

Luego puede usar el proyecto de código abierto como http://tfschangelog.codeplex.com para generar notas de la versión. Tiene una versión de GUI y una versión de línea de comando que facilita la programación de informes de notas de versión cada noche.

Las notas de publicación pública deben contener al menos:

  • lanzamiento, buildnumber
  • todos los errores públicos fijos
  • todas las funciones públicas añadidas

Las notas de la versión QA deben contener al menos:

  • lanzamiento, buildnumber
  • todos los errores solucionados, incluido el número de error
  • todas las funciones añadidas, incluidos enlaces a documentos de diseño

Considera a tu audiencia y trata de pensar lo que necesitan.

Otra cosa para agregar es el soporte nuevo o discontinuo para ciertas plataformas. (Por ejemplo, dejamos de admitir Win3.1 y agregamos Vista 64 bit).

Realmente depende de la audiencia. Para los usuarios técnicos (por ejemplo, los desarrolladores que usan su API) puede ser muy técnico. En el otro extremo, los usuarios finales de alto nivel de una aplicación que usted creó tal vez solo estén interesados ​​en nuevas funciones y cambios importantes.

En el medio hay usuarios no técnicos que también necesitan los detalles, por ejemplo, el departamento de soporte. Para esas personas, puede dar una descripción detallada sin las especificaciones técnicas de bajo nivel, por ejemplo, "Se corrigió un error en el que el registro no se guardaba en la base de datos".

Si tiene un sistema de administración de proyectos / seguimiento de problemas, definitivamente debe usarlo para generar sus notas de lanzamiento. Trac y Redmine en particular son muy buenos en esto.

Los puntos de lanzamiento deben tener algunas propiedades, IMO:

  • Recuerde a su audiencia Si se trata de una aplicación de iPhone, pocos se preocuparán por el hecho de que se corrigió un error de lógica particular en la línea 572 de la clase Foo. Pero les importará mucho que "la aplicación ahora sea sensible al acelerómetro".
  • Resume los nuevos desarrollos, características y correcciones de errores de una manera amplia y amplia si es posible. Si puede unirlos temáticamente (por ejemplo, "implementamos genéricos y tipos anónimos"), una breve reseña sobre eso es una buena manera de dar a la gente una idea general.
  • Detalla las cosas específicas que se arreglaron, con enlaces a tu rastreador de errores público, si hay alguno. Esto generalmente se puede generar automáticamente.
  • No proporcione detalles insoportables. Los resúmenes de uno o dos líneas de cada cosa que se agregó o fijó deberían ser suficientes.
  • Siempre incluya identificadores de versiones específicos (por ejemplo, "v.1.4.5"), según corresponda.