Cómo etiquetar versiones en Git

Las etiquetas (tags) en Git son referencias que apuntan a puntos específicos en el historial de Git. A diferencia de las ramas, las etiquetas no cambian una vez creadas. Se utilizan principalmente para marcar versiones importantes de tu proyecto (v1.0.0, v2.0.0, etc.), lo que facilita la gestión y el acceso a diferentes versiones del código.

¿Qué son las etiquetas en Git?

Las etiquetas son simplemente punteros a commits específicos, similar a las ramas, pero con una diferencia fundamental: mientras que las ramas se mueven a medida que se añaden nuevos commits, las etiquetas permanecen fijas, señalando siempre al mismo commit.

Existen dos tipos principales de etiquetas en Git:

1. Etiquetas ligeras: Son simplemente un puntero a un commit específico, sin información adicional.
2. Etiquetas anotadas: Contienen metadatos adicionales como el nombre del etiquetador, fecha, mensaje de etiqueta y pueden ser firmadas con GPG.

Creando etiquetas

Etiquetas ligeras

Para crear una etiqueta ligera, simplemente usa el comando git tag seguido del nombre de la etiqueta:

git tag v1.0.0

Esto creará una etiqueta llamada "v1.0.0" que apunta al commit actual (HEAD).

Etiquetas anotadas (recomendadas)

Para crear una etiqueta anotada, usa la opción -a y proporciona un mensaje con -m:

git tag -a v1.0.0 -m "Versión 1.0.0 - Primera versión estable"

Las etiquetas anotadas son preferibles para marcar versiones porque:

• Almacenan información adicional sobre quién creó la etiqueta y cuándo
• Incluyen un mensaje descriptivo
• Pueden ser verificadas criptográficamente (si están firmadas)

Etiquetar commits anteriores

También puedes etiquetar commits anteriores especificando el hash del commit:

git tag -a v0.9.0 -m "Versión beta" 9fceb02

Donde 9fceb02 es el inicio del hash del commit que deseas etiquetar.

Convenciones de nomenclatura para etiquetas

Es una práctica común usar el prefijo "v" seguido del número de versión semántico:

v[MAYOR].[MENOR].[PARCHE]

Ejemplos:

• v1.0.0: Primera versión estable
• v1.2.3: Versión 1, característica 2, parche 3
• v2.0.0-beta.1: Primera versión beta de la versión 2.0.0

Esta convención es ampliamente reconocida y facilita la identificación de etiquetas de versión en el repositorio.

Visualizando etiquetas

Listar todas las etiquetas

Para ver todas las etiquetas en tu repositorio:

git tag

Listar etiquetas con un patrón

Para filtrar etiquetas según un patrón:

git tag -l "v1.*"

Esto mostrará todas las etiquetas que comiencen con "v1.".

Ver detalles de una etiqueta

Para ver información detallada sobre una etiqueta anotada:

git show v1.0.0

Esto mostrará el mensaje de la etiqueta, quién la creó y el commit al que apunta.

Compartiendo etiquetas

Por defecto, el comando git push no transfiere etiquetas al repositorio remoto. Debes hacerlo explícitamente.

Enviar una etiqueta específica

git push origin v1.0.0

Enviar todas las etiquetas

git push origin --tags

Enviar etiquetas al hacer push de ramas

Para enviar etiquetas automáticamente al hacer push de ramas:

git config --global push.followTags true

Con esta configuración, cuando hagas git push, Git también enviará las etiquetas que apunten a commits que estás enviando.

Checkout a etiquetas

Puedes hacer checkout a una etiqueta para examinar el estado del código en esa versión:

git checkout v1.0.0

Esto te pondrá en un estado "detached HEAD" (HEAD separada), lo que significa que no estás en ninguna rama. Si necesitas hacer cambios basados en esta etiqueta, deberías crear una nueva rama:

git checkout -b fix-for-v1.0.0 v1.0.0

Eliminando etiquetas

Eliminar una etiqueta local

git tag -d v1.0.0

Eliminar una etiqueta remota

git push origin --delete v1.0.0

Etiquetas firmadas con GPG

Para mayor seguridad, puedes firmar tus etiquetas con GPG:

git tag -s v1.0.0 -m "Versión firmada 1.0.0"

Para verificar una etiqueta firmada:

git tag -v v1.0.0

Esto verifica la firma y muestra el mensaje de la etiqueta.

Estrategias de etiquetado para diferentes flujos de trabajo

Etiquetado para versionado semántico

Siguiendo SemVer (MAYOR.MENOR.PARCHE):

1. Versiones estables: v1.0.0, v1.1.0, v2.0.0
2. Pre-lanzamientos: v1.0.0-alpha.1, v1.0.0-beta.1, v1.0.0-rc.1
3. Parches: v1.0.1, v1.0.2

Etiquetado para releases periódicos

Para proyectos con ciclos de lanzamiento regulares:

1. Basado en fechas: v2023.01, v2023.02 (año.mes)
2. Versiones trimestrales: v2023-Q1, v2023-Q2

Etiquetado para entornos

En flujos de trabajo con múltiples entornos:

1. Producción: production-2023-04-15
2. Staging: staging-2023-04-10
3. QA: qa-2023-04-05

Integración con herramientas de CI/CD

Las etiquetas son fundamentales en flujos de trabajo de integración continua y entrega continua:

GitHub Actions

name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build
        run: |
          # Comandos de compilación
      - name: Create Release
        uses: actions/create-release@v1
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}

GitLab CI

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - echo "Building..."
  only:
    - tags

deploy:
  stage: deploy
  script:
    - echo "Deploying version $CI_COMMIT_TAG"
  only:
    - tags

Automatización del etiquetado

Usando scripts para crear etiquetas

Puedes automatizar la creación de etiquetas con scripts:

#!/bin/bash
# Incrementa la versión PATCH y crea una etiqueta

# Obtener la última etiqueta
LATEST_TAG=$(git describe --tags --abbrev=0)

# Incrementar la versión PATCH
# Ejemplo: v1.0.0 -> v1.0.1
NEXT_TAG=$(echo $LATEST_TAG | awk -F. '{$NF = $NF + 1;} 1' OFS=.)

# Crear la nueva etiqueta
git tag -a $NEXT_TAG -m "Versión $NEXT_TAG"

# Enviar la etiqueta al remoto
git push origin $NEXT_TAG

Usando herramientas de versionado

Herramientas como npm version pueden ayudar a gestionar etiquetas:

# Incrementa la versión PATCH y crea una etiqueta
npm version patch

# Incrementa la versión MINOR y crea una etiqueta
npm version minor

# Incrementa la versión MAJOR y crea una etiqueta
npm version major

Buenas prácticas para el etiquetado

1. Usa etiquetas anotadas para versiones

Las etiquetas anotadas proporcionan más contexto y son más adecuadas para marcar versiones importantes.

git tag -a v1.0.0 -m "Versión 1.0.0: Descripción de los cambios principales"

2. Sigue una convención de nomenclatura consistente

Establece y sigue una convención clara para nombrar tus etiquetas.

3. Etiqueta solo commits estables

Asegúrate de que el código funcione correctamente antes de etiquetarlo como una versión.

4. Documenta los cambios

Incluye información detallada en el mensaje de la etiqueta o referencia a un archivo CHANGELOG.

git tag -a v1.0.0 -m "Versión 1.0.0

- Característica A implementada
- Error B corregido
- Rendimiento de C mejorado

Ver CHANGELOG.md para más detalles."

5. No modifiques etiquetas publicadas

Una vez que has compartido una etiqueta, no deberías modificarla o moverla a otro commit.

6. Usa etiquetas firmadas para releases oficiales

Para releases oficiales, considera firmar tus etiquetas con GPG para verificar la autenticidad.

git tag -s v1.0.0 -m "Versión oficial 1.0.0"

Casos de uso avanzados

Crear un archivo comprimido desde una etiqueta

Puedes crear un archivo comprimido del código en una etiqueta específica:

git archive --format=zip v1.0.0 > v1.0.0.zip

Comparar cambios entre etiquetas

Para ver los cambios entre dos versiones etiquetadas:

git diff v1.0.0 v1.1.0

Crear una rama desde una etiqueta antigua

Si necesitas realizar cambios basados en una versión anterior:

git checkout -b hotfix/1.0.1 v1.0.0

Encontrar cuándo se creó una etiqueta

Para ver cuándo se creó una etiqueta específica:

git for-each-ref --format="%(creatordate) %(refname)" refs/tags/v1.0.0

Solución de problemas comunes

Etiqueta ya existe

Problema: Error al intentar crear una etiqueta que ya existe.

Solución: Elimina la etiqueta existente primero o usa un nombre diferente.

git tag -d v1.0.0
git tag -a v1.0.0 -m "Nuevo mensaje"

Etiqueta no se envía al remoto

Problema: Las etiquetas no aparecen en el repositorio remoto después de hacer push.

Solución: Envía las etiquetas explícitamente.

git push origin --tags

Conflicto entre etiqueta local y remota

Problema: La etiqueta local y remota apuntan a diferentes commits.

Solución: Elimina la etiqueta local, obtén la remota y recrea la local si es necesario.

git tag -d v1.0.0
git fetch --tags

Conclusión

Las etiquetas en Git son una herramienta poderosa para marcar puntos importantes en la historia de tu proyecto. Utilizadas correctamente, facilitan la gestión de versiones, la colaboración entre equipos y la implementación de flujos de trabajo de integración y entrega continuas.

Al combinar etiquetas con el versionado semántico y buenas prácticas de documentación, puedes crear un sistema robusto para gestionar el ciclo de vida de tu software y comunicar claramente los cambios a los usuarios y colaboradores.

En la próxima lección, exploraremos cómo usar git tag específicamente para marcar lanzamientos y cómo esto se integra con el flujo de trabajo general de desarrollo.