Subdirección de las Tecnologías de la Información y Comunicaciones
Área de Gobernanza y Calidad
Contenido
Cumplimiento normativo
Las normas expuestas son de obligado cumplimiento. La STIC podrá atender casos excepcionales que serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo, cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad, según corresponda, y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC. La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto. En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica. Contacto Dpto: Oficina de Calidad |
Histórico de cambios
Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución, ordenándose de más recientes a menos recientes.
|
Introducción
Todos los proyectos software ejecutados para la STIC deben construirse y desarrollarse en base a los requisitos técnicos y tecnológicos que la infraestructura del SAS soporta. En caso contrario, será necesaria la autorización por parte del Área de Gobernanza y Calidad que evaluará la propuesta realizada durante la reunión de lanzamiento del proyecto.
Uno de los objetivos del Área de Gobernanza y Calidad es asegurar que se dispone de productos desplegables en un entorno productivo y que se adecúen a las necesidades de los usuarios.
El presente texto recoge la normativa aplicable para la gestión de entregas del software desarrollado por y para la STIC. Con la aplicación de estas normas y recomendaciones, la STIC pretende:
- Definir los entregables.
- Definir la política de numeración de versiones.
- Implantar y normalizar el procedimiento de entrega de código fuente.
La gestión de las entregas del software desarrollado para la Subdirección de Tecnologías de la Información y Comunicaciones del Servicio Andaluz de Salud se realizará usando las herramientas, los procedimientos y las directrices establecidas en esta norma.
La STIC se está evolucionando a un nuevo modelo de gestión del ciclo de vida del software basado en la dupla APLICACION - COMPONENTES, con el objeto de simplificar y mejorar la gestión de las aplicaciones. Todo lo relacionado con un producto se va a gestionar en un único proyecto en JIRA. Cada una de las particiones independientes de una aplicación se denominarán componentes, que podrán ser del tipo módulo o librería. Actualmente este modelo se está pilotando en varios proyectos. En las distintas secciones de esta norma que lo requieran, se puntualizará la información a tener en cuenta en aquellos proyectos que vayan adoptando este modelo de gestión.
Entregables
Se parte de la premisa de que el código fuente de una aplicación, sus scripts de base de datos, y su correspondiente código compilado deben quedar almacenados en la infraestructura de la STIC (herramientas ALM), independientemente de la tecnología utilizada. Para materializar este objetivo, la suite de herramientas que cubren el ciclo de integración y entrega continua son:
- Sistema de control de versiones: GitLab (http://git.sas.junta-andalucia.es/).
- Servidor para la integración continua: Jenkins (http://ci.alm.sas.junta-andalucia.es/).
- Artefactos compilados, archivos de configuración y cualquier fichero necesario para el despliegue: DML (Nexus) (https://dml-si.sas.junta-andalucia.es/).
Para que el software objeto de la entrega sea correctamente gestionado, es necesario solicitar vía CGES tanto la creación del repositorio de código de la aplicación, como el job de Jenkins que realizará las operaciones que sean necesarias en función de la naturaleza del proyecto. Estas peticiones deben realizarse una vez registrada la aplicación y/o componente en CMS, lo más pronto posible (al inicio del proyecto), y siempre antes de la primera entrega. Si necesita conocer cómo darlas de alta, puede consultar el artículo Catálogo peticiones a la Oficina de Calidad vía CGES.
En la solicitud de alta de un nuevo componente en CMS, es necesario tener en cuenta que la nomenclatura del atributo "Código ALM", siempre debe basarse en la convención de nombres de la tecnología del proyecto y coincidirá con el nombre del repositorio en Git.
- Java, Node: Todo minúsculas y guiones medios
- .Net, Drupal, Delphi: CamelCase sin guiones
Para más información con respecto a CMS y la plantilla para el registro de una aplicación en el mismo, puede consultar el artículo Servicios de Gestión interna de la DGSIC#Plantillas
Otro aspecto a tener en cuenta es que, para la configuración del job de Jenkins, es necesario disponer del archivo readme.md correctamente cumplimentado. La plantilla a utilizar está disponible en el repositorio http://git.sas.junta-andalucia.es/gobernanza/ArchivosDeDesarrollo/recursos_sas. Es obligación del proveedor de desarrollo mantener constantemente actualizada la información incluida dentro de este fichero.
Al inicio de un proyecto NUEVO es necesario realizar una entrega "ficticia" con el pom.xml y el archivo readme.md y etiquetarla como 0.0.0.1 debido a que Sonarqube sólo analiza el incremento de código incluido desde la última entrega de la versión anterior. Así, de cara a la primera entrega para el despliegue de la aplicación, Sonarqube tendrá con qué comparar y los resultados del análisis aparecerán de forma correcta.
Los proyectos que comiencen a adoptar el nuevo modelo de gestión aplicación-componentes, deberán contactar con el jefe del proyecto del área de Coordinación y Estrategia, Olimpia Torres Barranco <olimpia.torres@soprasteria.com> , quien orquestará el inicio de todo el proceso y la gestión de las peticiones. |
Versionado
El versionado de las entregas, independientemente de la tecnología de desarrollo, deberá ser identificado con 4 dígitos, según la notación X.Y.Z.T (mayor.menor.revisión.entrega) donde X, Y, Z y T son números enteros no negativos, y NO DEBEN ser precedidos de ceros.
- mayor (X): indica la versión principal del software, consistiendo en un conjunto de funcionalidades concretas que son recogidas y cubiertas en dicha versión. Debe modificarse cuando la versión que se entregue presente nuevas funcionalidades claves de la aplicación respecto de la versión anterior. La modificación de esté dígito se realiza por la inclusión de nuevos requerimientos al sistema, tal y como la inclusión de nuevos módulos o una revisión completa de los existentes.
- menor (Y): indica la funcionalidad menor cubierta en la versión de software entregada. Debe ser modificado cuando hay cambios significativos en la forma en la que se ofrece la funcionalidad existente, cuando se corrigen grandes fallos del sistema, o cuando hay nuevas versiones evolutivas que modifican significativamente la funcionalidad ofrecida.
- revisión (Z): se modifica cuando hay revisiones de código ante fallos de la aplicación.
- entrega (T): este dígito indica el número de veces que un paquete ha sido entregado. La re entrega del producto podrá producirse para subsanar un defecto en el software detectado durante las etapas de revisión previas a su instalación, durante la propia instalación, o bien durante el periodo de pruebas anterior a su puesta en producción.
La primera versión estable de cualquier producto NUEVO debe comenzar en la 1.0.0.1. En el caso de que el producto ya exista y tenga una versión diferente, se entenderá que la primera versión dada de alta en el repositorio de código será congruente con la existente. Además:
- El campo versión en Jira debe informarse 3 dígitos según la notación mayor.menor.revisión.
- El campo entrega en Jira debe añadir un cuarto dígito a la versión identificada de la que depende, según la notación mayor.menor.revisión.entrega y, siempre, en consonancia con el versionado de las entregas de software realizadas en el repositorio de código de corporativo de la STIC.
Los proyectos que comiencen a adoptar el nuevo modelo de gestión aplicación-componentes, deberán tener en cuenta que el versionado de los componentes ha de cumplir las pautas definidas anteriormente. Además, para el versionado de la aplicación, se establece como buena práctica la adopción de los mismos criterios. La versión de la aplicación vendrá condicionada por la versión de sus componentes. Es decir:
|
Estructura del repositorio
Según la tecnología de desarrollo utilizada será necesario incluir carpetas específicas en el directorio que se definirán al inicio del proyecto por el Área de Gobernanza y Calidad. La estructura acordada se ha de documentar en el espacio Confluence propio del proyecto. La normativa aplicable para la operativa con el repositorio GIT puede encontrarse en el siguiente enlace. Los aspectos comunes a las diferentes tecnologías, relacionados con la configuración de las aplicaciones, están descritos en el artículo "Archivos de las aplicaciones. Consideraciones generales". |
Organización de los proyectos
La organización del proyecto en Git seguirá las siguientes directrices:
- Debe existir un repositorio para el código. Se ha de solicitar el alta con el nombre del código ALM de la aplicación en CMS.
Debe existir un repositorio para las pruebas. Almacenará todos los ficheros .features de las aplicaciones que utilizan metodología agile y/o automatización de pruebas funcionales. Se solicitará el alta con el nombre: <código ALM de la aplicación en CMS>-testproject. Puede consultar todos los detalles de la estructura interna en el ANEXO II: Estructura del repositorio testproject.
- Ambos estarán englobados en un grupo. Se solicitará su alta con el nombre del código ALM de la aplicación en CMS.
Estructura del repositorio de código para proyectos JAVA
El objeto del repositorio de proyectos para el control del versiones es el almacenamiento de manera exclusiva del código fuente y los procedimientos que permiten obtener el código binario asociado a ese código fuente del aplicativo. Quedan excluidos del repositorio los ficheros relacionados con la gestión o documentación del proyecto (ficheros del tipo .eap .doc, etc). El incumplimiento de esta directriz conllevará el rechazo de la PL asociada a la entrega de código fuente .
Partiendo de la directriz marcada en el párrafo anterior y de la estructura que proporciona la tecnología MAVEN para los proyectos JAVA, todos los repositorios incluidos en la herramienta de control de versiones (GIT) tienen que estar organizados según la estructura común que a continuación se indica:
Directorio | Contenido |
pom.xml (para proyectos basados en Maven) o build.xml (para proyectos basados en Ant) | En la carpeta raíz es donde se almacenará el fichero. |
scripts | Contiene todos los ficheros necesarios para construir el modelo de datos. La estructura interna de esta carpeta se define en el siguiente enlace. |
| pruebasdecarga | Contiene todos los ficheros relacionados con las pruebas de carga del sistema. La estructura interna de esta carpeta se define en el artículo Pruebas de carga del sistema. |
Estructura del repositorio de código para otras tecnologías NO JAVA
Desarrollo PHP
Para los desarrollos con tecnología PHP, el código fuente deberá estar estructurado según las pautas comunes:
Estructura del repositorio para tecnología PHP
Directorio | Contenido |
|---|---|
scripts | Contiene todos los ficheros necesarios para construir el modelo de datos. La estructura interna de esta carpeta se define en el siguiente enlace. |
| pruebasdecarga | Contiene todos los ficheros relacionados con las pruebas de carga del sistema. La estructura interna de esta carpeta se define en el artículo Pruebas de carga del sistema. |
Desarrollos VB6 y .NET
Para los desarrollos .NET, el código fuente estará estructurado según las pautas definidas en el documento de definición del Framework Base .NET desarrollado en base a la Arquitectura de Referencia .NET y referenciado en el documento de Normas de Desarrollo .NET publicado en este espacio.
Los scripts de BBDD serán incluidos en un directorio (cuyo nombre debe ser scripts) identificado a tal efecto dentro del mismo paquete de software.
Estructura del repositorio de código para tecnología VB6 y .NET
Directorio | Contenido |
|---|---|
scripts | Contiene todos los ficheros necesarios para construir el modelo de datos. La estructura interna de esta carpeta se define en el siguiente enlace. |
| pruebasdecarga | Contiene todos los ficheros relacionados con las pruebas de carga del sistema. La estructura interna de esta carpeta se define en el artículo Pruebas de carga del sistema. |
Desarrollos ENSEMBLE
Para los desarrollos realizados con tecnología ENSEMBLE e incorporados al repositorio de código no existe una estructura de directorios específica. Estos desarrollos son incorporados al repositorio como un fichero con formato XML plano.
Otros desarrollos: Cobol, Delphi, PowerBuilder, business intelligence
El resto de proyectos existentes en la STIC, con tecnología Cobol, Delphi y PowerBuilder, o aquellos proyectos enfocados dentro del área de business intelligence, mantendrán la estructura de directorios existente actualmente debiéndose incluir, los scripts de BBDD en un directorio (cuyo nombre debe ser scripts) identificado a tal efecto dentro del mismo paquete de software.
Estructura del repositorio para tecnología Cobol, Delphi y PowerBuilder
Directorio | Contenido |
|---|---|
scripts | Contiene todos los ficheros necesarios para construir el modelo de datos. La estructura interna de esta carpeta se define en el siguiente enlace. |
En el modelo de gestión aplicación-componentes se deberá tener en cuenta que la organización en GitLab pretende replicar la de JIRA. Habrá un grupo equivalente a la aplicación JIRA en el que estarán incluidos los repositorios correspondientes a los distintos componentes. Así, por ejemplo, existirá una aplicación en JIRA llamado ESTACION CLINICA DE CUIDADOS VERSION WEB, en el que se gestionará todo lo relacionado con esta aplicación y con los componentes que la forman:
En GitLab existirá un grupo llamado estacion_clinica_cuidados (su nombre corresponderá con el código ALM de la aplicación en CMS), que englobará a todos los componentes de la aplicación. Cada componente tendrá su propio repositorio. http://git.sas.junta-andalucia.es/asistencial/diraya/estacion_clinica_cuidados
En CMS, la aplicación aparece con su número de entrega y agrupando a sus componentes que también tienen informada su correspondiente entrega. Un aspecto importante a tener en cuenta es la entrega de las pruebas. El código de las pruebas automatizadas y sus correspondientes archivos .features se entregarán dentro de un componente denominado <CALM>-testproject, donde CALM es el código ALM de la aplicación. El testproject se tratará como un componente más, y tendrá su propio repositorio, aunque su estructura interna será un poco distinta. Puede consultar todos los detalles en el ANEXO II: Estructura del repositorio testproject. |
Procedimiento de entrega
Para la entrega de código fuente en GIT, se almacenará en la rama principal (master) el código de la aplicación y cada entrega de código supondrá la creación de una nueva versión (tag) según lo establecido en la normativa GIT .
La entrega de código fuente se realizará accediendo a través de VPN al repositorio GIT correspondiente publicado en la dirección http://git.sas.junta-andalucia.es/ siguiendo el procedimiento:
|
Servicios de verificación previos a la petición de lanzamiento (PL)
Servicio de Verificación de la Entrega (SVE)
La Oficina de Calidad realiza una revisión de diversos aspectos relacionados con la entrega de la versión.
De forma general, las comprobaciones que se realizan son las siguientes:
Verificación del repositorio de código.
- Uso correcto de Gitflow.
- Etiquetado de la versión.
- Organización del proyecto en el repositorio.
Verificación y validación de la calidad estática de código.
- Revisión tarea Jenkins.
- Sonar: Métricas, umbrales, excepciones.
Artículo de referencia: "Verificación de la calidad del código fuente".
Con respecto a Sonarqube, hay que tener en cuenta una cuestión importante. Cuando se realiza una entrega, Sonarqube sólo analiza el incremento de código incluido desde la última entrega de la versión anterior. No se analiza el código completo de la aplicación, sólo el correspondiente a la versión que se pretende implantar.
Para que la primera comparativa se realice correctamente, es necesario realizar una entrega "ficticia" con el pom.xml y el archivo readme.md y etiquetarla como 0.0.0.1. Así, Sonarqube tendrá con qué comparar y los resultados del análisis aparecerán de forma correcta.
- Revisión script: CNO.
Artículo de referencia: "Normativa BBDD Oracle".
Comprobación del correcto empaquetado y ubicación en la DML.
En el momento de ejecutar la PL, CTI cogerá los binarios de Nexus. Por lo tanto, es imprescindible comprobar que se han subido correctamente. La ruta relativa de la ubicación de los binarios en la DML será la misma que su análoga para el código fuente en Git. En el caso de que no haya entrega de código fuente, la ruta será la indicada en el registro de entrega de binarios.
Por ejemplo:
Componente: estacion_clinica_cuidados_cliente_web
Entrega: 3.6.6.2
Por lo tanto en el PID correspondiente, habría que indicar que el binario se encuentra en Nexus, en la ubicación:
Ruta del componente: /asistencial/diraya/estacion_clinica_cuidados/estacion_clinica_cuidados_cliente_web/
Entrega: estacion_clinica_cuidados_cliente_web.3.6.6.2.zip
Motivos de rechazo
A continuación se muestra el listado de los motivos por los que una SVE se puede rechazar. De todos ellos, sólo la compilación fallida en Jenkins será bloqueante para la creación de la PL. El resto no la impedirá, quedando la decisión de seguir adelante, bajo responsabilidad del jefe de proyecto.
Estructura repositorio incorrecta (faltan carpetas/readme, etc ...)
Plantilla Readme.md mal informada
Incumplimiento CNO
GitFlow incorrecto (commits hechos en master o develop, merges mal hechos, etc ...)
Estructura y/o contenido incorrecto del Pom/Build
No cumple los umbrales de Sonarqube.
Compilación fallida en Jenkins
Este motivo de rechazo impedirá la creación de la PL en JIRA.
¿Cómo influye este nuevo modelo en el procedimiento de entrega? En cada entrega, tendremos una SVE de aplicación, vinculada a n SVE´s de componentes. Se procederá de la siguiente manera:
Motivos de rechazoLos motivos de rechazo de una SVE de aplicación son los mismos que los de cualquier otra SVE. Si cualquiera de las SVE´s de componente es rechazada, su correspondiente SVE de aplicación también lo será y en el caso que se rechacen varios componentes de la misma, se seleccionará como “Motivo” del rechazo el más restrictivo. |
Servicio de Verificación de Datos (SVD)
Como comentábamos en el apartado Procedimiento de entrega, existe un Servicio de de verificación (SVD) asociado a las PL de datos.
Tanto en el caso de carga como en el de correctivo de datos, se revisará que los scripts que se entregan cumple la Normativa BBDD Oracle publicada en el área de Gobernanza y Calidad.
Motivos de rechazo
Básicamente son dos:
Incumplimiento de CNO.
Los scripts incumplen la normativa.
Modificación de la línea base del aplicativo.
Se utiliza una PL de datos de forma incorrecta ya que se modifica, de alguna manera , el esquema de base de datos.
¿Cómo influye este nuevo modelo en el procedimiento de entrega? En cada entrega, se generará la SVD a nivel de aplicación. |
Consideraciones sobre la PL
A la hora de dar de alta una PL, se debe tener en cuenta que:
- Es necesario tener una SVE que poder asociar a la PL. En el caso de una PLU no es necesario que esté resuelta.
- Ya no se adjunta el PID. Ahora es un documento Confluence asociado a la PL. De hecho, no se adjunta ningún archivos a la PL.
- Como hemos comentado varias veces a lo largo de este artículo, CTI sólo va a tener acceso a la DML. Cualquier paquete necesario para un despliegue debe estar ubicado en Nexus.
Anexos
ANEXO I: Estructura de la carpeta scripts
La carpeta scripts dentro del repositorio del código fuente contendrá una carpeta por cada versión del producto realizada siguiendo la nomenclatura de 3 dígitos (en este caso, se obvian las diferentes reentregas de una misma versión).
Cada una de estas carpetas tendrá todos los scripts de base de datos necesarios para realizar la actualización del producto.
Salvo que la actualización del producto necesite instrucciones especiales, y de cara a una próxima automatización de tareas, se estandarizará la nomenclatura de los ficheros existentes dentro de estas carpetas, debiendo existir siempre dos ficheros llamados version_X.X.X.sql y undo_version_X.X.X.sql el cual se encargará de realizar la actualización completa del producto (Y la marcha atrás en el caso del undo) ya sea porque contenga todos los scripts necesarios o bien porque se encargue de invocar a otros sql dentro de la misma carpeta.
De esta forma, la estructura de carpetas y scripts quedará de la siguiente forma:
Ejemplo de contenido de la carpeta scripts
ANEXO II: Estructura del repositorio testproject
Testproject es un repositorio en el que se almacenan las pruebas y, caso de que lo hubiera, el código correspondiente a su automatización.
El proyecto sólo contiene pruebas
Algunas consideraciones:
- Si el proyecto almacena sólo el enunciado de las pruebas, es decir, si no se sube código, no es necesario que versione.
- Las pruebas se enlazarán, como es habitual, con su HU correspondiente.
- Se cumplirán las buenas prácticas en el manejo de Git (no commits en develop, creación de feature para las subidas, ...).
La organización del repositorio se consesuará con la STIC. Por efecto, se escogerá entre:
- Si existen subsistemas funcionales en el proyecto:
- Modelo aplicación-componente: root/ código ALM de la aplicación-testproject/features/$Subsistemafuncional$/
- Modelo tradicional: root/código ALM de la aplicación-testproject/features/$Subsistemafuncional$/
- Si NO existen subsistemas funcionales definidos en el proyecto:
- root/código ALM de la aplicación-testproject/features/
El proyecto contiene pruebas y código
Si el repositoriro Testproject almacena código de automatización de pruebas:
- Actuará como un componente más del proyecto.
- Versionará de forma independiente, como cualquier otro repositorio.
- La gestión del código cumplirá con la normativa establecida.
Toda la información con los detalles sobre la estructura interna del repositorio Testproject se encuentra en : Automatización de pruebas funcionales
La carpeta "feature"
Aunque todos los detalles relacionados con la estructura del Testproject así como las principales directrices de codificación se encuentran en el artículo Automatización de pruebas funcionales, hay que hacer mención especial a la carpeta en la que se entregan los archivos .feature.
Desde el punto de vista de la organización, es importante señalar que las pruebas se agruparán, siempre que sea posible, en áreas funcionales que llamaremos Subsistemas. Cada uno de ellos tendrá asociado un código.
- El código del subsistema será numérico.
- La relación entre el subsistema y su código quedará reflejada en una tabla que se publicará en el espacio de Confluence del proyecto correspondiente.
| ID | SUBSISTEMA |
|---|---|
| 001 | $Subsistemafuncional$ |
| 002 | $Subsistemafuncional2$ |
| 003 | $Subsistemafuncional3$ |
| 004 | $Subsistemafuncional4$ |
En el caso de que se adopte un modelo de aplicación-componente, la tabla tiene la siguiente estructura:
|