Changes between Version 19 and Version 20 of TolPackageRulesAndComments

Timestamp:

Oct 13, 2010, 10:42:00 AM (14 years ago)

Author:

Víctor de Buen Remiro

Comment:

--

TolPackageRulesAndComments

@@ -108 +108 @@
   ]] };
    }}}
-=== Nomenclatura y versionado ===
-
- * Los nombres de los paquetes deben seguir el estilo CamelCase 
- * No puede haber paquetes con el mismo nombre de NameBlock ni en el mismo ni 
-   en distinto repositorio, pues todos los paquetes compartirán un mismo
-   almacén de cliente vengan del repositorio que vengan.
- * El nombre del archivo de una versión concreta de un paquete se obtiene
-   como la concatenación del nombre del paquete seguido de un punto, el número 
-   _.autodoc.version.high, otro punto y el número _.autodoc.version.low
- * El nombre del NameBlock sin embargo es el mismo siempre, por lo que se invocará 
-   sin usar los números de versión.
- * No es posible por tanto cargar dos versiones distintas de un mismo paquete en
-   la misma sesión TOL.
- * Sí es posible cargar diferentes versiones de un mismo NameBlock en una misma
-   máquina en sesiones de TOL distintas, coincidentes o no en el tiempo.
+=== Control de versiones ===
+
+El objetivo del control de versiones es que en el repositorio se puedan almacenar todas las 
+versiones binarias de cada paquete que hayan sido publicadas de forma histórica, pues sólo de 
+esta forma se puede asegurar que cada usuario pueda utilizar la versión compatible con todo 
+su sistema, y que pueda a lo largo del tiempo, y accediendo a las novedades que le interesen 
+fijando su propio ritmo de actualización, sin tener que estar siempre a la última, lo cual 
+puede ser peligroso en sistemas de mantenimiento de producción en tiempo real, ni tampoco 
+atándose a una versión congelada que no admite mejora ninguna.
+
+ * El nombre del archivo en el que se almacena una versión concreta de un paquete se obtiene 
+   como la concatenación del nombre del paquete, que debe coincidir con el miembro redundante 
+   {{{_.autodoc.name}}}, seguido de un punto, el número {{{_.autodoc.version.high}}}, otro 
+   punto y el número {{{_.autodoc.version.low}}}. 
+ * El nombre del NameBlock sin embargo es el mismo siempre, a lo largo de toda la evolución 
+   del paquete, por lo que se invocará sin usar los números de versión, salvo en la orden 
+   {{{#Require}}}, si se desea cargar una versión concreta.
+ * No es posible por tanto cargar dos versiones distintas de un mismo paquete en la misma 
+   sesión TOL.
+ * Sí que es posible cargar diferentes versiones de un mismo NameBlock en una misma máquina 
+   en sesiones de TOL distintas, coincidentes o no en el tiempo.
+ * No puede haber paquetes con el mismo nombre de NameBlock ni en el mismo ni en distinto 
+   repositorio, pues todos los paquetes compartirán un mismo  almacén de cliente vengan 
+   del repositorio que vengan. El sistema de instalación y mantenimiento de paquetes debe 
+   avisar si existen conflictos entre distintos repositorios.
+ * De forma opcional el paquete puede incorporar en _.autodoc.versionControl información 
+   adicional sobre el mecanismo de control de versiones utilizado en su desarrollo 
+   (SVN, CVS, ...) que indique cómo recuperar el código fuente exacto con el que fue 
+   construido el paquete. Esta información podría usarse de forma manual y sólo en caso de 
+   tener que rehacer un paquete antiguo que se hubiera perdido o que se quisiera modificar 
+   por un problema grave, y que fuera requerido en algún proceso de vital importancia. 
+   Llegados a este caso habría que plantearse si el paquete modificado debe sobreescribir el 
+   existente en el repositorio o se debe usar sólo de forma local donde se precise.
+
+==== Nomenclatura ====
+
+ Aunque no hay ninguna normativa general al respecto, salvo en el caso del repositorio 
+ público oficial de TOL en el que serán de obligado cumplimiento, se aconseja tomar las 
+ siguientes medidas con respecto a la nomenclatura de los paquetes:
+ 
+ * Los nombres de los paquetes deberían seguir el estilo CamelCase que permite una mayor 
+   claridad y una mejor organización de los mismos si se reservan partículas con 
+   significado preestablecido.
+ * Aumentar el primer número de forma secuencial progresiva de uno en uno, empezando 
+   desde el 1, reservando el 0 para versiones de pruebas no publicadas. Sólo se debería 
+   modificar si se da un cambio, o una acumulación de cambios, que suponga alteraciones 
+   importantes en el modo de uso o las capacidades del paquete. 
+ * Aumentar el segundo número cada vez que se modifica el paquete en cualquier cosa que 
+   pueda ser incompatible con lo anterior en cualquier aspecto por pequeño que sea. Si 
+   no se modificara al publicarlo sobreescribirá el anterior y será imposible que los 
+   usuarios utilicen la versión eliminada si por cualquier motivo la nueva no les sirve.
+ * Cuando se aumenta el primer número se debería reiniciar el segundo.
+ * Al segundo dígito se le puede intentar dotar de cierta semántica propia del paquete 
+   o de u proyecto o departamento, obligando a que tengan más o menos cifras. Por ejemplo, 
+   podrían ser de la forma XxYy, con X,Y=1..9; x,y=0..9; significando Yy para cierto 
+   tipo de cambios menores o más frecuentes y Xx para otros de mayor calado.
+ * Si se produce un cambio meramente ornamental, de documentación, o que resuelva un 
+   problema menor que no pueda tener ningún tipo de efecto secundario se puede 
+   sobreescribir el paquete publicado, aunque esto debería hacerse sólo como último 
+   recurso, lo más aconsejable es acumular esos pequeños cambios para la siguiente 
+   versión.
+
+==== Dependencias ====
+
+ * Cada versión de un paquete requiere de una versión mínima de TOL dada por el 
+   miembro _.autodoc.minTolVersion que asegura su funcionamiento, aunque podría ser 
+   que funcionara con versiones anteriores, sin que sea fácil asegurarlo a ciencia 
+   cierta. Es de vital importancia revisar este campo antes de publicar una nueva 
+   versión de un paquete si ha habido cambios en la versión de TOL que pudieran 
+   afectarle y que hubieran ocurrido desde la publicación de la última versión del 
+   paquete. En principio sólo es preciso actualizar {{{_.autodoc.minTolVersion}}} 
+   si se hace uso de alguna nueva capacidad de TOL, lo cual no siempre es trivial 
+   conocer. En caso de duda es mejor actualizar de más que de menos.
+ * Cuando un paquete requiere de otros se debe incluir las correspondientes 
+   sentencias #Require antes de la declaración del primer miembro.
+ * Cuando el {{{#Require}}} no menciona la versión concreta del paquete que se 
+   desea cargar entonces se utilizará la versión más moderna existente localmente 
+   que sea compatible con la versión del TOL con el que se esté trabajando. 
+ * Si se solicita una versión concreta, entonces se debe cargar previamente cada 
+   uno de los paquetes requeridos directa o indirectamente. 
+ * Téngase en cuenta que no es posible cargar versiones concretas de paquetes que 
+   tengan requerimientos de diferentes versiones de un mismo paquete.
+ * La definición del paquete siempre debe usar #Require sin especificar una
+   versión concreta.
+ * Obsérvese que los paquetes requeridos se deben especificar por duplicado:
+   primero en los #Require sin comillas y luego en Set _.autodoc.dependencies
+   entre comillas pues esta información la necesita el gestor de repositorios.
+ * No está permitido el requerimiento cíclico directo ni indirecto entre 
+   paquetes, es decir, si A requiere a B directa o indirectamente B no puede 
+   requerir a A ni directa ni indirectamente. El sistema gestor de repositorios
+   caería en un ciclo infinito y no hay forma de detectarlo luego es 
+   responsabilidad de los desarrolladores del repositorio el evitarlo.
 
 === Código declarativo ===
@@ -182 +259 @@
    }}}
 
-=== Dependencias ===
-
- * Cuando un paquete requiere de otros se debe incluir las correspondientes
-   sentencias #Require antes de la declaración del primer miembro.
- * Si no se especifican números de versión el #Require cargará la versión más 
-   actual compatible con la versión de TOL que se esté ejecutando. En el
-   caso de la última versión de TOL, corresponderá al archivo con el nombre del 
-   paquete nada más. En este caso, los paquetes que requiera directa o 
-   indirectamente serán también las últimas versiones compatibles con TOL.
- * Si se solicita una versión concreta, entonces se debe cargar previamente cada 
-   uno de los paquetes requeridos directa o indirectamente. El propio 
-   {{{#Require}}} se encargará de buscar las versiones adecuadas en el 
-   repositorio local, de instalarlas si no las encuentra, y de dar un mensaje 
-   de error si no lo consigue para que se haga manualmente.
- * Téngase en cuenta que no es posible cargar versiones concretas de paquetes que 
-   tengan requerimientos de diferentes versiones de un mismo paquete.
- * La definición del paquete siempre debe usar #Require sin especificar una
-   versión concreta.
- * Obsérvese que los paquetes requeridos se deben especificar por duplicado:
-   primero en los #Require sin comillas y luego en Set _.autodoc.dependencies
-   entre comillas pues esta información la necesita el gestor de repositorios.
- * No está permitido el requerimiento cíclico directo ni indirecto entre 
-   paquetes, es decir, si A requiere a B directa o indirectamente B no puede 
-   requerir a A ni directa ni indirectamente. El sistema gestor de repositorios
-   caería en un ciclo infinito y no hay forma de detectarlo luego es 
-   responsabilidad de los desarrolladores del repositorio el evitarlo.
+
 
 === Documentación y chequeo de calidad ===
@@ -266 +318 @@
    un repositorio antes de publicar las actualizaciones de los paquetes para 
    asegurar la compatibilidad conjunta de todos ellos.
-