Crear Release en GitHub

Crea una release de GitHub etiquetada con notas de release y artefactos opcionales.

Cuándo Usar

• Al marcar una versión estable de software para distribución
• Al publicar una nueva versión de una biblioteca o aplicación
• Al crear notas de release para las partes interesadas
• Al distribuir artefactos de compilación (binarios, tarballs)

Entradas

• Requerido: Número de versión (versionado semántico)
• Requerido: Resumen de cambios desde la última release
• Opcional: Artefactos de compilación para adjuntar
• Opcional: Si es una pre-release

Procedimiento

Paso 1: Determinar el Número de Versión

Sigue el versionado semántico (

MAJOR.MINOR.PATCH

):

Cambio	Ejemplo	Cuándo
MAJOR	1.0.0 -> 2.0.0	Cambios incompatibles hacia atrás
MINOR	1.0.0 -> 1.1.0	Nuevas funcionalidades, compatible hacia atrás
PATCH	1.0.0 -> 1.0.1	Solo corrección de errores

Esperado: Se elige un número de versión que refleja con precisión el alcance de los cambios desde la última release.

En caso de fallo: Si no estás seguro de si los cambios son incompatibles, revisa el diff de la API pública. Cualquier eliminación o cambio de firma de una función exportada es un cambio incompatible que requiere incrementar MAJOR.

Paso 2: Actualizar la Versión en los Archivos del Proyecto

• DESCRIPTION

  (paquetes R)

• package.json

  (Node.js)

• Cargo.toml

  (Rust)

• pyproject.toml

  (Python)

Esperado: El número de versión se actualiza en el archivo de proyecto apropiado y se hace commit al control de versiones.

En caso de fallo: Si la versión ya se actualizó en un paso anterior (por ejemplo, mediante

usethis::use_version()

en R), verifica que coincida con la versión de release prevista.

Paso 3: Escribir las Notas de Release

Crea o actualiza el changelog. Organiza por categoría:

## What's Changed

### New Features
- Added user authentication (#42)
- Support for custom themes (#45)

### Bug Fixes
- Fixed crash on empty input (#38)
- Corrected date parsing in UTC (#41)

### Improvements
- Improved error messages
- Updated dependencies

### Breaking Changes
- `old_function()` renamed to `new_function()` (#50)

**Full Changelog**: https://github.com/user/repo/compare/v1.0.0...v1.1.0

Esperado: Las notas de release están organizadas por categoría (funcionalidades, correcciones, cambios incompatibles) con referencias a issues/PRs para trazabilidad.

En caso de fallo: Si los cambios son difíciles de categorizar, revisa

git log v1.0.0..HEAD --oneline

para reconstruir la lista de cambios desde la última release.

Paso 4: Crear Etiqueta Git

git tag -a v1.1.0 -m "Release v1.1.0"
git push origin v1.1.0

Esperado: Existe una etiqueta anotada

v1.1.0

local y en el remoto.

git tag -l

muestra la etiqueta.

En caso de fallo: Si la etiqueta ya existe, elimínala con

git tag -d v1.1.0 && git push origin :refs/tags/v1.1.0

y vuelve a crearla. Si el push es rechazado, asegúrate de tener acceso de escritura al remoto.

Paso 5: Crear la Release en GitHub

Usando GitHub CLI (recomendado):

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes-file CHANGELOG.md

Con artefactos:

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes "Release notes here" \
  build/app-v1.1.0.tar.gz \
  build/app-v1.1.0.zip

Pre-release:

gh release create v2.0.0-beta.1 \
  --title "v2.0.0 Beta 1" \
  --prerelease \
  --notes "Beta release for testing"

Esperado: Release visible en GitHub con etiqueta, notas y artefactos adjuntos (si los hay).

En caso de fallo: Si

gh

no está autenticado, ejecuta

gh auth login

. Si la etiqueta no existe en el remoto, súbela primero con

git push origin v1.1.0

.

Paso 6: Generar Notas de Release Automáticamente

GitHub puede generar notas automáticamente a partir de los PRs fusionados:

gh release create v1.1.0 \
  --title "v1.1.0" \
  --generate-notes

Configura las categorías en

.github/release.yml

:

changelog:
  categories:
    - title: New Features
      labels:
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
    - title: Documentation
      labels:
        - documentation
    - title: Other Changes
      labels:
        - "*"

Esperado: Las notas de release se generan automáticamente a partir de los títulos de los PRs fusionados, categorizadas por etiqueta.

.github/release.yml

controla las categorías.

En caso de fallo: Si las notas generadas automáticamente están vacías, asegúrate de que los PRs fueron fusionados (no cerrados) y tenían etiquetas asignadas. Como alternativa, escribe las notas manualmente.

Paso 7: Verificar la Release

# List releases
gh release list

# View specific release
gh release view v1.1.0

Esperado:

gh release list

muestra la nueva release.

gh release view

muestra el título, etiqueta, notas y activos correctos.

En caso de fallo: Si la release no aparece, revisa la pestaña Actions en busca de flujos de trabajo de release que puedan haber fallado. Verifica que la etiqueta exista con

git tag -l

.

Validación

• La etiqueta de versión sigue el versionado semántico
• La etiqueta Git apunta al commit correcto
• Las notas de release describen con precisión los cambios
• Los artefactos (si los hay) están adjuntos y son descargables
• La release es visible en la página del repositorio GitHub
• El indicador de pre-release está correctamente establecido

Errores Comunes

• Etiquetar el commit equivocado: Verifica siempre

  git log

  antes de etiquetar. Etiqueta después del commit de actualización de versión.
• Olvidar subir las etiquetas:

  git push

  no sube etiquetas. Usa

  git push --tags

  o

  git push origin v1.1.0

  .
• Formato de versión inconsistente: Decide entre

  v1.0.0

  y

  1.0.0

  y mantén la coherencia.
• Notas de release vacías: Proporciona siempre notas significativas. Los usuarios necesitan saber qué cambió.
• Eliminar y recrear etiquetas: Evita modificar etiquetas después de subirlas. Si es necesario, crea una nueva versión en su lugar.

Habilidades Relacionadas

• commit-changes

  - flujo de trabajo de staging y commit

• manage-git-branches

  - gestión de ramas para preparar una release

• release-package-version

  - flujo de trabajo de release específico para R

• configure-git-repository

  - requisito previo de configuración Git

• setup-github-actions-ci

  - automatizar releases mediante CI