Nerbdank.GitVersioning (NBGV) es una herramienta diseñada para automatizar el versionado semántico en proyectos de software, vinculando directamente el historial de confirmaciones (commits) de Git con los metadatos de los ensamblados y paquetes generados. Al centralizar la configuración en un archivo version.json, los equipos de desarrollo pueden eliminar la fricción asociada con el mantenimiento manual de números de versión.

Configuración Inicial del Archivo version.json

El punto de partida para adoptar esta herramienta es la creación del archivo de manifiesto en la raíz del repositorio. Este documento actúa como la fuente única de verdad para el cálculo de versiones.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "2.1-alpha"
}

Incluir la definición de $schema habilita el autocompletado en editores compatibles con JSON. Es un requisito estricto que el nombre del archivo esté completamente en minúsculas. Además, cualquier modificación realizada debe ser confirmada en el repositorio local para que el motor de NBGV pueda leer el historial correctamente.

Parámetros Avanzados de Control

El esquema de configuración admite múltiples directivas para afinar el comportamiento del versionado en distintos entornos de integración continua.

{
  "version": "2.0-rc",
  "assemblyVersion": {
    "version": "2.0",
    "precision": "build"
  },
  "pathFilters": [
    ":/src/core",
    ":/src/shared"
  ],
  "publicReleaseRefSpec": [
    "^refs/heads/main$",
    "^refs/tags/release-v\\d+\\.\\d+"
  ],
  "cloudBuild": {
    "setVersionVariables": true,
    "buildNumber": {
      "enabled": true,
      "includeCommitId": {
        "when": "nonPublicReleaseOnly",
        "where": "buildMetadata"
      }
    }
  },
  "versionHeightOffset": 50
}

En este ejemplo, se han establecido reglas específicas:

• Precisión de Ensamblado: El atributo AssemblyVersion se limitará al nivel de compilación (build), evitando el incremento automático de revisiones menores que suelen romper la compatibilidad binaria.
• Filtros de Ruta: El cálculo de la altura de la versión (version height) solo tendrá en cuenta los commits que afecten a los directorios src/core y src/shared.
• Despliegue Público: Solo las ramas main o etiquetas que coincidan con el patrón release-vN.N se considerarán versiones públicas estables.
• Integración en la Nube: Se inyectarán variables de entorno en el sistema CI/CD y se añadirá el hash corto del commmit a los metadatos de compilación exclusivamente para releases internos.
• Offset de Altura: Se añade un valor base de 50 al contador de commits, útil al migrar desde sistemas de versionado heredados.

Herencia de Configuración en Monorepositorios

Para soluciones que alojan múltiples componentes, NBGV permite la herencia de configuraciones. Un archivo raíz define la versión base, mientras que los subdirectorios pueden extenderla.

Configuración Raíz:

{
  "version": "4.5"
}

Configuración del Subproyecto:

{
  "inherit": true,
  "prerelease": "nightly"
}

Bajo este esquema, el componente específico se compilará con la etiqueta 4.5-nightly, mientras que el resto del repositorio conservará la versión estable 4.5.

Inyección de Metadatos en el Proceso de Compilación

Durante la ejecución de MSBuild, la herramienta intercepta el flujo de compilación para inyectar dinámicamente atributos en el código fuente. Propiedades como AssemblyInformationalVersion y PackageVersion se resuelven matemáticamente basándose en la distancia entre el commit actual y el último cambio en el archivo de versión.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <!-- NBGV inyecta automáticamente estas propiedades -->
    <GenerateAssemblyInfo>true</GenerateAssemblyInfo>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Nerdbank.GitVersioning" Version="3.6.133" PrivateAssets="all" />
  </ItemGroup>
</Project>

Al empaquetar el proyecto (por ejemplo, mediante dotnet pack), el archivo .nupkg resultante heredará automáticamente la cadena de versión calculada, incluyendo el hash de Git para trazabilidad en entornos de preproducción.

Resolución de Incidencias Comunes

• Estancamiento de la Versión: Si el número de compilación no se incrementa, verifique que los cambios en version.json hayan sido confirmados en el índice de Git. La herramienta opera sobre el historial confirmado, no sobre archivos de trabajo sin rastrear.
• Fallos de Validación de Esquema: Los errores de parseo generalmente derivan de comas faltantes o llaves sin cerrar. Valide la sintaxis estricta del formato JSON.
• Diagnóstico Local: Utilice la herramienta de línea de comandos nbgv ejecutando nbgv get-version en la terminal para inspeccionar los valores exactos que el motor inyectará en la próxima compilación.