Sección 7: identificación de la configuración

La adecuada identificación de la configuración es de vital importancia para la gestión eficiente de un Proyecto. La selección coherente de qué se va a administrar, cómo se va identificar, dónde se almacenará y cómo se resguardarán o, en caso de pérdida, cómo se restaurarán los ítems de configuración, es fundamental para garantizar la calidad en los procesos de Diseño y Desarrollo.

7.1. Criterios de selección de los ítems de configuración

La selección de los activos/ítems de configuración generados a lo largo de la consecución del Proyecto MoSimPa se hará en base a la política de que todo lo que agregue valor al producto y todo lo que constituya evidencia de su desarrollo será considerado como tal.

Los ítems de configuración identificados, que serán puestos bajo gestión de configuración, son hasta el momento los que se detallan a continuación:

  • El grupo mosimpa en Gitlab con sus metadatos y proyectos.

  • Todo proyecto dentro de Gitlab posee un repositorio git. Por la naturaleza de este tipo de repositorios se posee versiones completas de cada uno de los archivos commiteados en el mismo con sus modificaciones. Por este motivo se considera a un repositorio un activo en si mismo, un todo con sus contenidos.

  • Todos los archivos generados a partir de los anteriores que no sean incluídos en un repositorio git:

    • Imagen del SO.
    • Paquetes Debian conteniendo la versión binaria (compilada) del software.
    • Repositorios Debian para poder distribuir los paquetes anteriormente descriptos.

7.1.1 Contenido de los repositorios

Dentro de cada repositorio podrán encontrarse distintos activos en función del tipo de repositorio.

Repositorios de software

Estos repositorios contienen código fuente junto a los archivos necesarios para su correcto manejo y/o documentación del desarrollador.

Repositorios de hardware

Contienen los esquemáticos y diseños de PCB necesarios para la fabricación del hardware asociado.

Repositorio de documentación

Este repositorio aloja la documentación del proyecto:

  • Planes definidos en el proyecto (Plan de Gestión de Proyecto, Plan de Gestión de Riesgos, Plan de Gestión de la Configuración, Plan de Testing, etc.),
  • Documentos de especificación de requerimientos,
  • Documentos de arquitectura,
  • Diagramas (workflows, diagramas UML),
  • Informes de ensayos/testing,
  • Informes de avances,
  • Detalles del SOUP (Software Of Unknown Provenance),
  • etc.

y es de hecho el repositorio que aloja a este documento.

Durante el transcurso del Proyecto podrán surgir nuevos ítems a configurar, los cuales deberán comunicarse al Administrador de Configuración, quien deberá agregarlos al presente Plan.

La documentación se llevará a cabo en formato Markdown siempre que sea posible. Excepciones notables pueden ser archivos binarios documentales que serán raramente modificables, como un PDF. Para ello es bueno primero definir los componentes básicos de un documento en formato Markdown.

Todo archivo que se encuentre dentro de este repositorio automáticamente es un activo que se encuentra bajo control, por la naturaleza misma de un repositorio.

La forma primaria de renderización de este repositorio (pero no necesariamente la única) es a través de la utilización de la aplicación MkDocs. Es por esto que la estructura mínima de este repositorio responde al siguiente árbol:

.
├── docs
│   ├── images
│   │   └── paraayudar.png
│   └── index.md
├── scripts
├── mkdocs.yml
└── README.md

Donde:

  • El directorio docs contendrá la documentación a renderizar.
    • El directorio docs/images contendrá imágenes utilizadas al renderizar cosas en general, como el logo del proyecto.
  • El directorio scripts contendrá scripts necesarios para automatizar tareas de renderizado y/o generación de índices.
  • El archivo mkdocs.yml sirve de configuración para el renderizado.
  • El archivo README.md hace una breve descripción del propósito del repositorio.

7.1.2 Estructura de un documento en formato Markdown

Un documento en formato Markdown puede estar compuesto por uno o mas de:

  • Archivos de texto plano en formato Markdown y extensión .md
  • Archivos complementarios: imágenes, sonidos, PDFs y todo archivo que sirva para agregar valor al documento.

Para ordenar un documento se propone la siguiente estructura:

MiDocumento/
├── 01.md
├── 05.md
├── 06_01.md
├── 06_03.md
├── 08.md
├── files
│   ├── diagrama_de_flujo.png
│   ├── diagrama_de_flujo.uxf
│   ├── informe.pdf
│   └── logo.png
├── README.md.in
└── README.md

Donde:

  • El nombre del documento se establece en el nombre de directorio raíz. En el ejemplo "MiDocumento".
  • Los archivos .md contienen una o mas de las secciones del documento y se nombran a partir de la primer sección que contienen. Del ejemplo:
    • 01.md contiene las secciones 1, 2, 3 y 4.
    • 05.md contiene la sección 5.
    • 06_01.md contiene la sección 6 subsecciones 1 y 2.
    • 06_03.md contiene la sección 6 subsecciones 3 en adelante y la sección 7.
    • 08.md contiene la sección 8 y posibles otras secciones posteriores.
    • Directorio files contiene a los archivos complementarios requeridos por el documento.
    • README.md.in y README.md conforman los archivos de índice. El archivo README.md.in poseerá el texto que se desee de base en en índice mientras que el archivo README.md se generará a partir de un script (ver mas adelante), los archivos dentro del documento y el archivo README.md.in. Es decir que README.md será un archivo generado y no se pretende que un usuario lo edite directamente.

Se permite que un documento linkee:

  • a otro archivo fuera de su árbol siempre y cuando se encuentre alojado en el mismo repositorio.
  • a recursos accesibles a través de internet, como por ejemplo un link a la Wikipedia.

La primer linea de todo archivo .md debe arrancar con la linea:

[TOC]

Esto indica a MkDocs que genere una tabla de contenidos del documento, sin importar si el tema utilizado muestra o no una tabla.

7.2. Estándar de nomenclatura de los ítems de configuración

7.2.1 Path/ruta a los documentos

Haciendo uso de que un repositorio es un activo en si mismo la nomenclatura y orden de los archivos hará uso también del path/ruta en el que se encuentran.

En la siguiente tabla se detalla donde se deberán encontrar los activos de cada tipo de proceso que impulsa la generación del ítem de configuración:

Tipo de proceso de generación de IC Path/ruta en el repositorio documentation
Gestión de la Configuración (Configuration Management) docs/ConfigurationManagement/
Documentación del producto docs/ProductDocumentation/
Integración de Producto docs/ProductIntegration/
Planeamiento del proyecto docs/ProjectPlanning/
Ingeniería de Requerimientos docs/RequirementDevelopment
Gestión de Riesgos (Risk Management) docs/RiskManagement/
Solución técnica (DyD) docs/TechnicalSolution/
Verificación y Validación docs/VerificationAndValidation

Cada documento tendrá entonces un lugar dentro de este árbol de directorios, y, según lo visto en la sección "Estructura de un documento en formato Markdown", estará contenido en un directorio propio dentro del mismo. Por ejemplo este documento se encontrará en la ruta:

docs/ConfigurationManagement/PLN_Gestion_Configuracion/

7.2.2 Tipo de documentos y como nombrarlos

El nombre de directorio de cada documento en formato Markdown deberá comenzar con un acrónimo de 2 a 4 letras que refleje el tipo de activo del cual trata. A continuación se detallará la nomenclatura que será empleada específicamente en el Proyecto MoSimPa; las demás notaciones se alinean a las definidas en el Documento Control de Documentos y Registros. En el caso de necesitar algún acrónimo específico para el Proyecto, se deberá definir a continuación en este Documento.

Tipo de ítem de configuración Acrónimo
Check lists CHK
Ejemplos EJEM
Especificación de Arquitectura del Software (Software Architecture Specification) SAS
Especificación de Requerimientos del Software (Software Requirement Specification) SRS
Folletos FOLL
Guías GUIA
Informe INF
Manuales MAN
Minutas de reunión MIN
Modelo MOD
Planes PLN
Procedimiento PRO
Registros REG
Tableros/Tablas de datos TBL

En caso de ausencia de algún tipo de nomenclatura para un ítem de configuración se deberá notificar al Administrador de la Configuración para su definición e incorporación al presente Plan.

7.2.3 Tipos de archivo

El tipo de un archivo específico será determinado por su extensión. Algunos tipos de archivo típicos de este proyecto son:

Extensión Tipo de archivo
.md Archivo de texto con caracteres Unicode UTF-8 y formato Markdown
.pdf Archivo Portable Document Format
.png Imágen PNG
.uxf Archivo de texto con formato XML para uso con Umlet/Umletino para la generación de diagramas

En caso de ausencia de algún tipo de extensión para un ítem de configuración se deberá notificar al Administrador de la Configuración para su definición e incorporación al presente Plan.

Para los repositorios de software y hardware los tipos de archivos serán determinados por las características propias de las herramientas de uso de cada repositorio.

7.2.4 Estándar de nomenclatura para SOUP

Por otra parte, para todo ítem de configuración identificado como SOUP se deberá contar con un procedimiento de identificación propio. Éste deberá incluir el título del ítem SOUP, datos del fabricante y una designación única. Ver Guía de identificación de los SOUP.

7.2.4.1. SOUP incluido dentro de la PC/RaspberryPi

La imagen del Sistema Operativo se genera usando https://gitlab.com/mosimpa/pi-gen/ . Cuando se genera la imagen se generan dos archivos:

  • La imagen en si con nombre YYYY_MM_DD_mosimpa-server-mosimpaserver.img
  • Un archivo que lista los paquetes instalados en la imagen creada.

Esa lista es un activo que debe conservarse para documentación de la imagen. De la lista hay que separar los paquetes que se pueden considerar SOUP y los que se deben considerar OTS.

A la lista de paquetes anterior se le suman otros paquetes durante el paso de “Primer booteo y configuración” que deberán ser catalogados entre SOUP/OTS.

Para identificar este SOUP utilizaremos los siguientes parámetros:

  • Nombre del paquete de software.
  • Versión del paquete: incluye versión del software original y versión de empaquetado.
  • Arquitectura.
  • Descripción del paquete.
  • Datos del equipo de desarrollo.

7.2.4.2. SOUP incluido en el firmware del dispositivo

Para este SOUP podemos utilizar el formato propuesto:

Item SOUP Versión Datos
ArduinoJson 6.15.1 https://arduinojson.org/
Wire 1.0.1 https://github.com/espressif/arduino-esp32
WiFi 1.0 https://github.com/espressif/arduino-esp32
Ticker 1.0 https://github.com/espressif/arduino-esp32
EEPROM 1.0.3 https://github.com/espressif/arduino-esp32
ESPmDNS 1.0 https://github.com/espressif/arduino-esp32
PubSubClient 2.7 https://github.com/knolleary/pubsubclient.git
WiFiClientSecure 1.0 https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFiClientSecure

Las bibliotecas Wire, WiFi, Ticker, EEPROM y ESPmDNS pertenecen al Board Support Package (BSP) de Espressif para su ESP32.

7.2.5. Estándar de nomenclatura de líneas base de configuración

Cada línea de base de configuración creada se nombrará de acuerdo al siguiente esquema:

LBC_ACRÓNIMO:X.Y

Donde:

  • LBC: Corresponde a la Línea Base de Configuración en cuestión.
  • ACRÓNIMO: Corresponde a la tipificación de la LBC, eg.: ALC: Alcance; DES: Desarrollo; PROD: Producto.
  • X.Y: Corresponde al número de versión. Ej: 1.0.

7.3. Política de Backup y Restore

La información del proyecto MoSimPa se encuentra hosteada en una instancia de gitlab.com. Para realizar backups es necesario seguir el procedimiento descripto en https://docs.gitlab.com/ee/user/group/settings/import_export.html#exporting-a-group para bajar los contenidos. Repetir el procedimiento para cada proyecto. Los archivos bajados se copiarán al directorio /home/lisandro/mosimpa del NAS del grupo de trabajo, que a su vez está sujeto a backup por un servidor interno.

Para restaurar los datos se puede generar una nueva instancia en gitlab.com o instalar GitLab localmente y seguir los procedimientos descriptos en https://docs.gitlab.com/ee/user/group/settings/import_export.html#importing-the-group.

La tarea se simplificaría mucho si la instancia de GitLab fuese local, ya que es posible hacer backup de toda la instancia.

El responsable de realizar los backups será Lisandro D. N. Pérez Meyer con una periodicidad al menos mensual.