Versionado en GitHub con Releases

Aunque Git proporciona etiquetas (tags) para marcar puntos específicos en la historia de un repositorio, GitHub amplía esta funcionalidad con su característica de "Releases" (Lanzamientos). Las GitHub Releases te permiten no solo marcar versiones específicas de tu software, sino también proporcionar notas de lanzamiento detalladas y adjuntar archivos binarios compilados para su descarga.

¿Qué son las GitHub Releases?

Una GitHub Release es una forma de empaquetar y proporcionar software, notas de cambios y archivos binarios a los usuarios. Cada release está asociada a una etiqueta Git específica y puede incluir:

1. Título y descripción: Información sobre la versión y sus cambios
2. Notas de lanzamiento: Documentación detallada de las nuevas características, correcciones y cambios
3. Archivos adjuntos: Binarios compilados, documentación o cualquier otro archivo relevante

Las releases son especialmente útiles para proyectos de código abierto, ya que proporcionan una manera estandarizada para que los usuarios finales accedan a tu software sin necesidad de compilarlo desde el código fuente.

Diferencias entre Tags y Releases

Crear una Release en GitHub

Método 1: A partir de un tag existente

1. Navega a tu repositorio en GitHub
2. Haz clic en "Releases" en la barra lateral derecha
3. Haz clic en "Draft a new release" (Crear un nuevo lanzamiento)
4. Selecciona el tag existente en el menú desplegable
5. Completa el formulario con título, descripción y archivos
6. Haz clic en "Publish release"

Método 2: Crear un nuevo tag y release simultáneamente

1. Navega a tu repositorio en GitHub
2. Haz clic en "Releases" en la barra lateral derecha
3. Haz clic en "Draft a new release"
4. Escribe un nuevo nombre de tag (por ejemplo, "v1.0.0")
5. Selecciona la rama o commit específico para el tag
6. Completa el formulario con título, descripción y archivos
7. Haz clic en "Publish release"

Anatomía de una buena Release

Título

El título debe ser claro y seguir una convención consistente:

v1.0.0 - Nombre descriptivo

Descripción y notas de lanzamiento

Las notas de lanzamiento deben ser informativas y bien estructuradas:

## Nuevas características

- Implementación de autenticación con Google OAuth
- Añadido modo oscuro para la interfaz de usuario
- Soporte para exportación en formato CSV

## Correcciones

- Solucionado problema de rendimiento en la carga de imágenes
- Corregido error de validación en el formulario de registro
- Mejorada la compatibilidad con navegadores antiguos

## Cambios internos

- Actualizada la dependencia React a la versión 18.0
- Refactorizado el sistema de manejo de estados
- Mejorada la cobertura de pruebas automatizadas

## Agradecimientos

Gracias a @usuario1, @usuario2 y @usuario3 por sus contribuciones a esta versión.

Archivos adjuntos (Assets)

Los archivos adjuntos deben:

• Tener nombres descriptivos que incluyan la versión
• Estar disponibles para diferentes plataformas si es aplicable
• Incluir checksums (sumas de verificación) para validar la integridad

Ejemplos:

mi-aplicacion-v1.0.0-windows-x64.zip
mi-aplicacion-v1.0.0-macos.dmg
mi-aplicacion-v1.0.0-linux.tar.gz
checksums.txt

Tipos de Releases en GitHub

Pre-releases

Las pre-releases son versiones que aún no están listas para producción:

• Marcadas con una etiqueta como "Pre-release" en GitHub
• Útiles para versiones alfa, beta o candidatas a lanzamiento (RC)
• Permiten a los usuarios probar nuevas características antes del lanzamiento oficial

Para crear una pre-release, marca la casilla "This is a pre-release" al crear la release.

Latest Release

La "Latest Release" es la versión estable más reciente:

• Aparece destacada en la página principal del repositorio
• Es la versión recomendada para la mayoría de los usuarios
• Por defecto, la release más reciente que no sea una pre-release

Draft Releases

Los borradores de releases te permiten preparar una release sin publicarla:

• Solo visibles para colaboradores del repositorio
• Útiles para preparar notas de lanzamiento con anticipación
• Se pueden editar y modificar antes de hacerlas públicas

Automatización de Releases

GitHub Actions para Releases automáticas

Puedes automatizar la creación de releases con GitHub Actions:

name: Create Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Build project
        run: |
          npm install
          npm run build

      - name: Create Release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

      - name: Upload Release Asset
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./dist/app.zip
          asset_name: app.zip
          asset_content_type: application/zip

Semantic Release

Semantic Release es una herramienta que automatiza todo el flujo de trabajo de versionado:

• Determina automáticamente la próxima versión basada en los mensajes de commit
• Genera notas de lanzamiento basadas en los commits
• Publica la release en GitHub

Para configurarlo, añade un archivo .releaserc.json:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/github"
  ]
}

Buenas prácticas para GitHub Releases

1. Mantén un registro de cambios (Changelog)

Además de las notas de release, mantén un archivo CHANGELOG.md en tu repositorio:

# Changelog

## [1.0.0] - 2025-04-28

### Added
- Nueva característica A
- Nueva característica B

### Fixed
- Corrección de error X
- Corrección de error Y

## [0.9.0] - 2025-03-15

...

2. Sigue el versionado semántico

Como vimos en lecciones anteriores, utiliza SemVer para tus releases:

• MAJOR: Cambios incompatibles con versiones anteriores
• MINOR: Nuevas características compatibles con versiones anteriores
• PATCH: Correcciones de errores compatibles con versiones anteriores

3. Proporciona binarios para múltiples plataformas

Si tu software es multiplataforma, incluye binarios para cada sistema operativo:

• Windows (.exe, .msi, .zip)
• macOS (.dmg, .pkg)
• Linux (.deb, .rpm, .AppImage, .tar.gz)

4. Incluye instrucciones de instalación

Añade instrucciones básicas de instalación en las notas de lanzamiento:

## Instalación

### Windows
1. Descarga el archivo .exe
2. Ejecuta el instalador
3. Sigue las instrucciones en pantalla

### macOS
...

5. Destaca los cambios importantes

Resalta claramente los cambios importantes o potencialmente problemáticos:

## ⚠️ CAMBIOS IMPORTANTES

- La API v1 ha sido deprecada y será eliminada en la próxima versión
- La configuración del archivo config.json ha cambiado de formato

Gestión del ciclo de vida de las Releases

Deprecar versiones antiguas

Cuando una versión ya no es compatible:

1. Actualiza la descripción de la release para indicar que está deprecada
2. Añade información sobre a qué versión deberían actualizar los usuarios
3. Considera usar la etiqueta "Deprecated" en GitHub

Actualizar Releases existentes

Puedes editar una release después de publicarla:

1. Navega a la página de releases
2. Haz clic en "Edit" junto a la release
3. Actualiza la información o añade nuevos archivos
4. Haz clic en "Update release"

Conclusión

Las GitHub Releases son una poderosa extensión de las etiquetas Git que facilitan la distribución de software y la comunicación con los usuarios. Al proporcionar una interfaz estructurada para publicar versiones, notas de lanzamiento y binarios, las releases mejoran significativamente la experiencia tanto para los mantenedores como para los usuarios de un proyecto.

Dominar el uso de GitHub Releases te permitirá presentar tu software de manera profesional, mantener a los usuarios informados sobre los cambios y proporcionar una experiencia de actualización fluida. Combinado con el versionado semántico y las buenas prácticas de documentación, este sistema te ayudará a gestionar eficazmente el ciclo de vida de tu software.