Gestión de Proyectos de Software Libre (III). De numeración de versiones y documentación

proyectos software libreEn esta tercera entrega de la serie de posts sobre la gestión de software libre (traducción del texto original de Benjamin Mako Hill), “Mako” nos explica cómo numerar las versiones y qué documentación hay que hacer para el proyecto.

Eligiendo un método de numeración de versiones.

Lo más importante sobre un sistema de numeración de versiones es que tengas uno. Puede parecer pedante enfatizar este punto pero te sorprenderías cuántos scripts y pequeños programas aparecen sin ningún número de versión.

Lo segundo más importante sobre un sistema de numeración es que los números siempre van en sentido creciente. Los sistemas automáticos de versiones y el sentido del orden del universo se desintegrarán si los números de versiones no crecen. No importa si 2.1 es un gran salto y 2.0.005 es un pequeño salto pero sí importa que 2.1 sea más reciente que 2.0.005.

Sigue estas dos simples reglas y no fallarás (demasiado). A partir de aquí, la técnica más común parece ser la del esquema de numeración “nivel superior”, “nivel inferior”, “nivel de parche”. Ya te sea o no familiar el nombre, estás relacionado con él todo el tiempo. El primer número es el número superior y significa cambios o recodificaciones importantes. El segundo número es el inferior y representa funcionalidad añadida al principio de una estructura lo bastante coherente. El tercer número es el número de parche y normalmente se relaciona con arreglo de errores.

El uso extendido de este esquema me permite saber la naturaleza y el grado relativo de las diferencias entre el release 2.4.12 del kernel de Linux y el 2.4.11, 2.2.12 o el 1.2.12 sin saber nada de estos releases.

Puedes romper con estas reglas, como hacen algunos. Pero ten cuidado, si lo haces, alguien se enfadará, asumirá que no sabes, e intentará enseñarte, seguramente de manera no agradable. Yo siempre sigo este método y te imploro que lo hagas tú también.

Existen varios sistemas de numeración conocidos, útiles, y que valen la pena mirarlos antes de liberar tu primera versión.

Numeración de las versiones del Kernel de Linux.

El kernel de Linux utiliza un sistema de versiones que cualquier número de versión “inferior” impar se refiere a un release de desarrollo o prueba y cualquier número de versión “inferior” par se refiere a una versión estable. Piénsalo un momento. Bajo este sistema, los kernel 2.1 y 2.3 han sido y serán siempre kernels de desarrollo o prueba, y los kernel 2.0, 2.2 y 2.4 son código de producción con un grado superior de estabilidad y prueba.

Tanto si piensas en tener un modelo de desarrollo dividido1 (como se describe en la sección divisiones estables y en desarrollo) o liberar solo una versión cada vez, mi experiencia con varios proyectos de software libre y con el proyecto Debian me ha enseñado que el uso del sistema de numeración de versiones de Linux es digno de tenerse en cuenta. En Debian, todas las versiones “inferiores” son estables (2.0, 2.1, etc). No obstante, muchas personas asumen que 2.1 es una versión inestable o en desarrollo y continua usando una versión más antigua hasta que se ven tan frustrados por la carencia del progreso del desarrollo que se quejan y entonces entienden el sistema. Si nunca liberas una versión “inferior” impar sino solo versiones pares, nadie se perjudica, y hay menos personas confundidas. Vale la pena tener en cuenta esta idea.

Numeración de versiones de Wine:

Debido a la naturaleza inusual del desarrollo de Wine en donde el no-emulador está siendo constantemente mejorado pero no siendo trabajado hacia un objetivo específico, wine se libera cada tres semanas. Wine lo hace etiquetando sus releases en un formato “Año Mes Día” de forma que cada release se etiquettaría “wine-XXXXXXXX” donde la versión del 04 de Enero de 2000 sería “wine-20000104”. Para algunos proyectos, el formato “Año Mes Día” tiene mucho sentido.

Hitos del desarrollo de Mozilla:

Cuando alguien tiene en cuenta Netscape 6 y las versiones del proveedor, la estructura del desarrollo del proyecto mozilla es uno de los más complicados modelos de proyectos de software libre. La numeración de versiones del proyecto refleja la especial circunstancia en la que se ha desarrollado.

La estructura de la numeración de versiones de mozilla se ha elaborado históricamente en base a hitos. Desde el principio del proyecto mozilla, los objetivos del proyecto en el orden y grado de su consecución se trazaron en una serie de “road map”. Las mayores logros y puntos a conseguir se marcan como hitos en estos “road maps”. Por lo tanto, aunque Mozilla se compiló y distribuyó diariamente2 como “compilaciones de un día para otro”3, cuando un día se han conseguido los objetivos de un hito en el “road-map”, esta compilación se marca como “hito release”4.

Aunque no he visto este método empleado en otros proyectos hasta ahora, me gusta la idea y creo que podría ser valiosa en la división de pruebas o de desarrollo de una gran aplicación con un fuerte desarrollo.

Documentación.

Un gran número de aplicaciones software libres estupendas se han marchitado y muerto porque su autor fue la única persona que la conocía totalmente. Incluso si tu programa está escrito principalmente para un grupo de usuarios tecno-inteligentes, la documentación es de ayuda e incluso necesaria para la supervivencia de tu proyecto. Más adelante, en este documento, aprenderás en la sección llamada “liberando tu programa” que debes siempre liberar algo que se pueda utilizar. Un componente de software sin documentación no es utilizable.

Hay muchas personas diferentes que debes documentar y hay muchas maneras de documentar tu proyecto. La importancia de la documentación en el código fuente para facilitar el desarrollo por una gran comunidad es vital pero está fuera del alcance de este HOWTO. En nuestro caso, esta sección trata de tácticas útiles para la documentación dirigida a los usuarios.

Una combinación de tradición y necesidad ha tenido como consecuencia un sistema de documentación medio-habitual en la mayoría de proyectos de software libre que vale la pena seguir. Tanto usuarios como desarrolladores esperan poder acceder a la documentación de varias maneras y es esencial que proporciones la información que buscan de una manera que puedan leerla incluso si tu proyecto está a punto de “despegar”. Lo que se espera tener es:


Páginas Man.

Tus usuarios querrán poder teclear “man nombredetuproyecto” y que aparezca una página man bien formateada resaltando la utilización básica de tu aplicación. Comprueba que antes de liberar tu programa, lo hayas previsto.

Las páginas man no son difíciles de escribir. Hay una excelente documentación sobre el proceso de escritura de una página man en “The Linux Man-Page-HOWTO” que está accesible en el Linux Documentation Project (LDP) y está escrito por Jens Schweikhardt. Lo encontrarás en el Schweikhardt’s site o en la LDP.

También es posible escribir página man utilizando DocBook SGML. Dado que las páginas man son tan sencillas y el método DocBook relativamente nuevo, no he podido experimentar esta vía y agradeceré cualquier ayuda de alguien que pueda darme más información sobre cómo hacerlo.

Documentación accesible desde la línea de comandos.

La mayoría de usuarios esperarán alguna información básica fácilmente disponible desde la línea de comandos. Para algunos pocos programas este tipo de documentación se extenderá más de una pantalla (24 o 25 líneas) pero debería cubrir la utilización básica, una breve (una o dos frases) descripción del programa, una lista de comandos con explicaciones, así como las opciones más importantes (también con explicaciones), además de la manera de acceder a la documentación más detallada para aquellos que la necesiten. La documentación de la línea de comandos para el apt-get de Debian sirve como un excelente ejemplo y como modelo útil.

apt 0.3.19 for i386 compiled on May 12 2000 21:17:27Usage: apt-get [options] command apt-get [options] install pkg1 [pkg2 …] apt-get is a simple command line interface for downloading andinstalling packages. The most frequently used commands are updateand install. Commands: update – Retrieve new lists of packages upgrade – Perform an upgrade install – Install new packages (pkg is libc6 not libc6.deb) remove – Remove packages source – Download source archives dist-upgrade – Distribution upgrade, see apt-get(8) dselect-upgrade – Follow dselect selections clean – Erase downloaded archive files autoclean – Erase old downloaded archive files check – Verify that there are no broken dependencies Options: -h This help text. -q Loggable output – no progress indicator -qq No output except for errors -d Download only – do NOT install or unpack archives -s No-act. Perform ordering simulation -y Assume Yes to all queries and do not prompt -f Attempt to continue if the integrity check fails -m Attempt to continue if archives are unlocatable -u Show a list of upgraded packages as well -b Build the source package after fetching it -c=? Read this configuration file -o=? Set an arbitary configuration option, eg -o dir::cache=/tmpSee the apt-get(8), sources.list(5) and apt.conf(5) manualpages for more information and options.

Se ha convertido en una convención GNU el hacer este tipo de información accesible con las opciones “-h” y “–help”. La mayoría de usuarios GNU/Linux esperarán poder recuperar la documentación básica por estas vías por lo que si elijes utilizar otros métodos diferentes, estáte preparado para el fuego y la lluvia radiactiva.

Ficheros que esperarán los usuarios.

Además de las páginas man y la ayuda de la línea de comandos, existen con seguridad ficheros donde se buscará documentación, especialmente en los paquetes que contienen código fuente. En una distribución, la mayoría de estos ficheros pueden estar almacenados en el directorio root de la distribución o en un subdirectorio de root llamado “doc” o “Documentation”. Los ficheros que comúnmente se incluyen son:

README o Readme

Un documento que contiene la instalación básica, compilación, e incluso instrucciones básicas de utilización que maquilla la mínima información pura necesaria para conseguir poner en marcha y ejecutar el programa. Lo más probable es que un README no sea muy detallado pero debe ser conciso y efectivo. Un README ideal tiene al menos 30 lineas y no más de 250.

INSTALL o Install

El fichero INSTALL debería ser mucho más pequeño que el README y debería describir de forma concisa y rápida cómo compilar e instalar el programa. Normalmente un fichero INSTALL simplemente ordena al usuario ejecutar “./configure; make; make install” y menciona cualquier opción inusual o acciones que puedan ser necesarias. Para la mayoría de procedimientos de instalación estándar y programas, los ficheros INSTALL son lo más pequeño posible y raramente sobrepasan las 100 líneas.

CHANGELOG, Changelog, ChangeLog o changelog

Un CHANGELOG es un fichero sencillo que todo software libre bien gestionado debería incluir. Un CHANGELOG es sencillamente el fichero que, como su nombre indica, registra o documenta los cambios que se hacen a tu programa. La forma más sencilla de mantener un CHANGELOG es conservar un fichero con el código fuente de tu programa y añadir una sección al principio de CHANGELOG con cada release describiendo qué se ha cambiado, arreglado, o añadido al programa. Es una buena idea enviar también el CHANGELOG a la website porque puede ayudar a otros a la hora de decidir si necesitan actualizar a una nueva versión o esperar una mejoría más importante.

NEWS

Un fichero NEWS y un ChangeLog son parecidos. A diferencia del CHANGELOG, un fichero NEWS no se actualiza con nuevas versiones normalmente. Siempre que se añaden nuevas características, el desarrollador responsable creará una anotación en el fichero NEWS. Los ficheros NEWS no deberían cambiarse antes de una release (deberían estar al día todo el tiempo) pero es una buena idea comprobarlo ya que a menudo los desarrolladores olvidan mantenerlos al día como deberían.

FAQ

Para aquellos que no lo sepan, FAQ son las siglas de Frequently Asked Questions y un FAQ es exactamente un conjunto de preguntas frecuentes. Los FAQ no son difíciles de crear. Solo crea una política tal que si te hacen una misma pregunta o la ves en una lista de correo dos o más veces, añade la pregunta (y su respuesta) a tu FAQ. Los FAQ son más opcionales que los ficheros anteriores pero te pueden ahorrar tiempo, aumentar la usabilidad, y en cualquier caso disminuir los dolores de cabeza.

Website

Se trata indirectamente de una cuestión de documentación pero un buen website se está convirtiendo rápidamente en una parte esencial de cualquier proyecto de software libre. Tu website debería proveer acceso a tu documentación (si es posible en HTML). Debería también incluir una sección de noticias y acontecimientos relacionados con tu programa y una sección que detalla el proceso de involucrarse en el desarrollo o pruebas y ofrecer una invitación a todos los que lo deseen. Debería también suministrar enlaces a listas de correo, websites similares, y proveer un enlace directo a todas las formas posibles de descargar tu software.

Otros consejos sobre documentación.

  • Toda tu documentación debería ser en texto sin formato, o, en los casos en que está principalmente en tu website, en HTML. Todo el mundo puede crear un fichero de texto, todo el mundo tiene un beeper5, (casi) todo el mundo puede crear HTML. Puedes distribuir información en PDF, PostScript, RTF, o cualquier número de otros formatos muy utilizados pero esta información debe estar también disponible en texto sin formato o HTML o la gente se va a enfadar mucho contigo. Según mi opinión, el formato info entra en esta categoría. Existe mucha y muy buena documentación GNU que la gente simplemente no lee porque solo está en formato info. Y esto hace que la gente se enfade. No se trata de formatos importantes; se trata de accesibilidad y el status quo juega un papel importante en esta determinación.

  • No hace daño distribuir cualquier documentación para tu programa de tu website (FAQs etc) incluida con tu programa. No vaciles en incluirlo en el tarball6 del programa. Si la gente no lo necesita, lo borrará. Puedo repetirlo una y otra vez: Demasiada documentación no es pecado.

  • A menos que tu software se haya desarrollado para un idioma que no sea el inglés (por ejemplo un editor de textos en japonés), por favor distribúyelo con la documentación en inglés. Si no hablas inglés o no confías en tus aptitudes, pide ayuda a un amigo. Te guste o no, sea justo o no, el inglés es el idioma del software libre. No obstante, esto no significa que debas limitar tu documentación a solo en inglés. Si hablas otro idioma, distribuye traducciones de la documentación con tu software si tienes tiempo y energías para hacerlo. Siempre será de utilidad para alguien.

  • Para terminar, por favor comprueba la ortografía de tu documentación. Los errores ortográficos en la documentación son errores7. Yo soy propenso a cometer este error y es muy fácil caer en él. Si el inglés no es tu idioma nativo, consigue que alguien que sí lo sea lo revise o modifique tu documentación o páginas web. Una ortografía o gramática deficiente contribuirá a que tu código parezca poco profesional. En los comentarios del código fuente, este punto es menos importante pero en las páginas man y las páginas web estos errores no son aceptables.

1Del texto original “split development model”

2Del original “nigthly”.

3Del original “nightly builds”.

4Del original “milestone release”.

5Del original: Pager.

6Paquete preparado para ser compilado e instalado, generalmente construidos con el comando tar.

7Del original “bugs”.

Acerca de Isildur Fuentes

Apasionado de las buenas historias y aikidoka de la tierra.

Publicado el junio 22, 2011 en Divulgación, Escritos y etiquetado en , , , . Guarda el enlace permanente. Comentarios desactivados en Gestión de Proyectos de Software Libre (III). De numeración de versiones y documentación.

Los comentarios están cerrados.

A %d blogueros les gusta esto: