Documentación

Procesos de Calidad en el desarrollo de Software

Esta documentación es una base para poder implementar un código de calidad y aumentar la productividad de los entregables hacia el cliente, de una manera rápida y sistemática.

Cualquier inquetud que tengas puedes comunicarte a través de los medios que dispone Imaginamos para la comunicación interna de los desarrolladores.

Configuración de SonarQube en Local con Docker

1. Instalación y Configuración de SonarQube en Docker

Paso 1: Preparar el ambiente local

Requisitos:

• Tener Docker y Docker Compose instalados.
• 4 GB de RAM asignados a Docker.

Paso 2: Crear un archivo docker-compose.yml

Crea un archivo llamado docker-compose.yml en el directorio raíz del proyecto y añade el siguiente contenido:

version: "3"
services:
  sonarqube:
    image: sonarqube:lts-enterprise
    container_name: sonarqube
    ports:
      - "9000:9000"
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonarqube
      - SONAR_JDBC_USERNAME=sonar
      - SONAR_JDBC_PASSWORD=sonar
    networks:
      - sonarnet
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_extensions:/opt/sonarqube/extensions

  db:
    image: postgres:13
    container_name: sonarqube_db
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=sonar
      - POSTGRES_DB=sonarqube
    networks:
      - sonarnet
    volumes:
      - postgresql_data:/var/lib/postgresql/data

networks:
  sonarnet:
    driver: bridge

volumes:
  postgresql_data:
  sonarqube_data:
  sonarqube_logs:
  sonarqube_extensions:

Paso 3: Ejecutar SonarQube con Docker Compose

Ejecuta el siguiente comando en la terminal dentro del directorio donde está ubicado el archivo docker-compose.yml:

docker-compose up -d

Accede a SonarQube desde tu navegador en http://localhost:9000.

Paso 4: Configurar SonarQube

• Inicia sesión con las credenciales predeterminadas: admin/admin.
• Cambia la contraseña después de iniciar sesión.

Paso 5: Agregar un Proyecto a SonarQube

1. Selecciona Create new project.
2. Genera un token para el proyecto.
3. Sigue las instrucciones para agregar el análisis de código a tu proyecto (por ejemplo, con Maven o Gradle).

Paso 6: Ejecutar el análisis de SonarQube en el proyecto

Añade el archivo sonar-project.properties al directorio raíz del proyecto con el siguiente contenido:

sonar.projectKey=nombre-del-proyecto
sonar.host.url=http://localhost:9000
sonar.login=token-generado

Luego, ejecuta el siguiente comando:

sonar-scanner

2. Configuración de Quality Gates (QG)

Paso 1: Acceder a Quality Gates

Desde la interfaz de SonarQube, selecciona Quality Gates en el menú principal.

Paso 2: Crear un nuevo Quality Gate

Haz clic en Create para crear un nuevo Quality Gate y define las reglas necesarias, como la cobertura mínima de código.

Paso 3: Asignar el Quality Gate al proyecto

Ve a Administration > Projects, selecciona tu proyecto y asigna el nuevo Quality Gate.

3. Automatización del Proceso

Considera integrar SonarQube en tus pipelines de CI/CD (como Jenkins, GitLab CI, GitHub Actions) para automatizar el análisis de código en cada commit o pull request.

4. Solución de Problemas Comunes

Asegúrate de verificar los registros de SonarQube si hay problemas de conexión o rendimiento. Algunos errores comunes incluyen:

• Problemas de memoria asignada a Docker.
• Fallos de conexión con la base de datos PostgreSQL.
• Errores de autenticación al usar tokens incorrectos.

Guía del Desarrollador

Es una guía general sobre las buenas prácticas que se deben seguir en el desarrollo de funcionalidades. También encontrarás toda la documentación técnica y los flujos de trabajo recomendados por Imaginamos.

Convención de Conventional Commits

La convención de Conventional Commits utilizada en Angular sigue una estructura específica que ayuda a estandarizar los mensajes de commit, facilitando el entendimiento y la revisión de cambios. A continuación se detalla el formato y algunos ejemplos:

Formato General:

    <tipo>(<alcance opcional>): <descripción corta>

    <cuerpo opcional>

    <footer opcional>
    

Descripción de cada parte:

• Tipo: Describe la naturaleza del cambio. Algunos tipos comunes incluyen:
  • feat: Para una nueva funcionalidad.
  • fix: Para corregir un bug.
  • docs: Para cambios en la documentación.
  • style: Para cambios de estilo (formato, indentación) que no afectan la lógica del código.
  • refactor: Para refactorización de código sin agregar o corregir funcionalidad.
  • test: Para agregar o modificar pruebas.
  • chore: Para cambios que no afectan el código de producción, como actualizaciones de dependencias.
• Alcance (opcional): El área o módulo afectado por el cambio, colocado entre paréntesis después del tipo de commit.
• Descripción corta: Una breve descripción del cambio que no debe exceder los 72 caracteres.
• Cuerpo opcional: Descripción más detallada que proporciona contexto o explicaciones adicionales.
• Footer opcional: Para incluir notas adicionales, como referencias a issues (por ejemplo, Closes #123) o indicar breaking changes.

Ejemplos de Conventional Commits:

Agregar una nueva funcionalidad:

    feat(users): agregar soporte para autenticación por OAuth
    

Corregir un bug:

    fix(login): corregir el error al validar credenciales vacías
    

Actualizar la documentación:

    docs(readme): agregar instrucciones de configuración inicial
    

Cambios de estilo:

    style(header): corregir la indentación y eliminar espacios en blanco
    

Refactorización de código:

    refactor(api): optimizar el manejo de errores en las peticiones
    

Cambiar el proceso de construcción o actualizar dependencias:

    chore(deps): actualizar la versión de TypeScript a 4.3.5
    

Notas importantes:

La estructura de Conventional Commits ayuda a automatizar procesos como:

• Generar changelogs automáticamente.
• Gestionar el versionado semántico.
• Facilitar la revisión y entendimiento de los cambios realizados.

Puedes consultar la documentación oficial para obtener más detalles.

Introducción a Git Flow

Git Flow es una estrategia de branching (manejo de ramas) para Git que facilita la organización del ciclo de vida del desarrollo de software. Fue introducida por Vincent Driessen y se ha convertido en una metodología popular para gestionar el desarrollo colaborativo en equipos, permitiendo mantener la estabilidad del código en producción mientras se trabaja en nuevas características o correcciones.

El flujo Git Flow define una estructura clara de ramas con roles específicos para cada una de ellas:

• main: Es la rama principal, siempre lista para ser desplegada en producción. Solo contiene versiones estables del software.
• develop: Esta rama actúa como el punto de integración donde los desarrolladores combinan su trabajo. El código aquí está en constante evolución, pero debe estar lo suficientemente estable como para futuras versiones.
• feature branches: Son ramas temporales utilizadas para desarrollar nuevas características o mejoras. Una vez completada la tarea, se fusionan en la rama develop.
• release branches: Se crean a partir de develop cuando una nueva versión está lista para ser lanzada. Aquí se hacen pruebas y ajustes finales antes de fusionarse tanto en main como en develop.
• hotfix branches: Se utilizan para arreglar errores críticos en producción. Se crean a partir de main y, una vez que el problema se soluciona, la corrección se fusiona en main y develop.

Beneficios de Git Flow

• Organización clara: Diferentes ramas para diferentes propósitos permiten mantener el código más organizado.
• Control de versiones: Facilita la gestión de múltiples versiones del software en paralelo.
• Flujo controlado: Permite la integración continua y las pruebas antes de desplegar en producción, reduciendo riesgos.

Este flujo es ideal para proyectos donde se necesita mantener versiones de producción estables, mientras se desarrollan nuevas funcionalidades de forma simultánea.

Git Flow en Imaginamos

Proceso para la Implementación de Features/Fixes y Validación de Calidad de Código con SonarQube

1. Clonación del Repositorio
   El desarrollador debe clonar el repositorio remoto al entorno local para contar con una copia actualizada del código fuente en su máquina. Esto garantiza que el trabajo se realiza con la versión más reciente del proyecto.
2. Creación de una Nueva Rama (feature o fix)
   Partiendo de la rama de desarrollo (por ejemplo, develop), se crea una nueva rama que sigue el esquema de nombres establecido, utilizando prefijos como feature/ o fix/, dependiendo de si se trata de una nueva funcionalidad o de la corrección de un error. Esto permite aislar los cambios específicos del desarrollo en curso.
3. Desarrollo de la Feature/Fix y Commits
   En esta fase, se implementan los cambios necesarios para completar la feature o corregir el fix. Cada avance significativo en el desarrollo se guarda mediante un commit. Es importante que los mensajes de commit sigan el estándar de conventional commits definido por la empresa, asegurando claridad y consistencia en el historial de cambios.
4. Ejecución del Escáner de SonarQube
   Una vez que se han realizado los cambios en el código, se ejecuta el escáner de SonarQube para validar que el código cumple con los Quality Gates establecidos. Este análisis detecta posibles errores, vulnerabilidades y asegura el cumplimiento de estándares de calidad y seguridad.
5. Validación de los Quality Gates en SonarQube
   En este paso, se revisa si el código ha cumplido con los Quality Gates mínimos definidos. Dependiendo del resultado, hay dos escenarios posibles:
   • No cumple con los Quality Gates
     Si el código no cumple con los mínimos establecidos (por ejemplo, por la presencia de errores o baja cobertura de pruebas), el desarrollador debe realizar correcciones y agregar nuevos commits que solventen los problemas identificados. Después, se vuelve a ejecutar el escáner de SonarQube.
   • Cumple con los Quality Gates
     Si el código pasa los Quality Gates, el desarrollador puede proceder a subir los cambios al repositorio remoto, subiendo la rama que contiene la feature o fix implementada.
6. Generación de la Pull Request (PR)
   Con la rama ya subida al repositorio remoto, se genera una Pull Request (PR) que apunta a la rama de desarrollo principal (generalmente develop o master). Este PR solicita la revisión de los cambios antes de ser integrados en la rama principal.
   • Subida de Evidencias
     Se adjunta una captura de pantalla o un reporte del análisis de SonarQube que muestra los resultados del escaneo, asegurando que los Quality Gates se han cumplido correctamente.
   • Revisión por Parte del Equipo
     El líder de equipo o un compañero desarrollador revisa la PR, verificando tanto la funcionalidad como la calidad del código, en base a las políticas del equipo.
   • Corregir según Sugerencias
     Si durante la revisión se encuentran aspectos por mejorar, el desarrollador debe corregir los cambios según las sugerencias, hacer los ajustes necesarios, y repetir el proceso desde el paso 3.
   • Fusión del PR
     Si la PR no tiene comentarios o sugerencias pendientes, se procede a fusionar la rama de la feature o fix en la rama de desarrollo principal, completando el ciclo de implementación.