Tipos de etiquetas: ligeras vs. anotadas

En Git, las etiquetas (tags) son referencias que permiten marcar puntos específicos en el historial del repositorio, como hitos importantes o versiones de lanzamiento. Existen dos tipos principales de etiquetas: ligeras y anotadas, cada una con características y propósitos diferentes.

Las etiquetas ligeras son sencillas y directas. Se comportan como una rama que no cambia; es decir, son un puntero inmutable a un commit específico. Estas etiquetas no almacenan información adicional, simplemente referencian el hash del commit.

Debido a su simplicidad, se crean muy rápido y ocupan menos espacio en el repositorio. Estas etiquetas se pueden utilizar para marcar versiones internas o referencias temporales que no requieren metadatos. Sin embargo, como no contienen información sobre quién creó la etiqueta o cuándo, no se recomienda su uso en contextos donde se necesita un historial detallado.

Por el contrario, las etiquetas anotadas son objetos propios en Git que almacenan metadatos importantes. Además de apuntar a un commit, incluyen campos como:

• Etiqueta: nombre de la etiqueta.
• Mensaje: descripción o notas sobre la versión.
• Autor: nombre y correo electrónico de la persona que creó la etiqueta.
• Fecha: momento en que se creó la etiqueta.
• Firma GPG (opcional): permite verificar la autenticidad mediante una firma criptográfica.

Las etiquetas anotadas se usan para marcadores permanentes, como versiones oficiales o releases de software. Como contienen información detallada, es más fácil el seguimiento y la auditoría del historial.

La principal diferencia entre las etiquetas ligeras y anotadas radica en la cantidad de información que almacenan. Mientras que las etiquetas ligeras son simplemente referencias a un commit, las etiquetas anotadas proporcionan un contexto más amplio y son la forma recomendada de etiquetar versiones en Git.

Cuando se utilizan etiquetas en un repositorio remoto, las anotadas son más útiles, debido a que otros desarrolladores podrán ver los metadatos asociados. Así, para versionado público y colaborativo, se prefieren las etiquetas anotadas.

Creación y gestión de tags: Comandos y convenciones de nombres

La creación y gestión de etiquetas (tags) sirve para marcar puntos significativos en el historial del repositorio, como lanzamientos de versiones. Para trabajar con etiquetas, Git tiene una serie de comandos que permiten crear, listar, borrar y compartir etiquetas con otros colaboradores.

Para crear una etiqueta ligera, se utiliza el comando:

git tag nombre_de_etiqueta

Este comando crea una etiqueta que apunta directamente al commit actual sin información adicional. Por ejemplo:

git tag v1.0

Creará una etiqueta llamada v1.0 en el commit actual.

Para crear una etiqueta anotada, que incluye metadatos como el autor, fecha y mensaje, se utiliza el comando -a (de "annotate") seguido del nombre de la etiqueta y la opción -m para agregar un mensaje:

git tag -a v1.0 -m "Primera versión estable"

Esta etiqueta anotada permite agregar una descripción que ayuda a identificar los cambios introducidos en esa versión.

Es posible etiquetar un commit específico proporcionando el hash o parte de él:

git tag -a v1.0 9fceb02 -m "Etiqueta en commit específico"

Para listar todas las etiquetas existentes en el repositorio, se utiliza:

git tag

Este comando mostrará todas las etiquetas ordenadas alfabéticamente. Si se quieren buscar etiquetas que coincidan con un patrón específico, se puede usar comodines:

git tag -l "v1.*"

Para ver la información detallada de una etiqueta anotada, se usa:

git show v1.0

Este comando muestra los metadatos de la etiqueta y los cambios introducidos en el commit asociado.

Si se necesita eliminar una etiqueta localmente, se utiliza:

git tag -d nombre_de_etiqueta

Por ejemplo:

git tag -d v1.0

Este comando solo elimina la etiqueta en el repositorio local. Para eliminar la etiqueta en el repositorio remoto, se debe ejecutar:

git push origin --delete nombre_de_etiqueta

Por ejemplo:

git push origin --delete v1.0

Para compartir etiquetas con el repositorio remoto, es necesario empujarlas explícitamente. Al hacer git push, las etiquetas no se envían por defecto. Así que para enviar una etiqueta específica, se usa:

git push origin nombre_de_etiqueta

O para enviar todas las etiquetas de una vez:

git push origin --tags

Las convenciones de nombres siguen unas pautas comunes como:

• Utilizar prefijos como v para indicar versiones, por ejemplo, v1.0.0, v2.1.5.
• Seguir el versionado semántico (SemVer), donde el formato es Mayor.Menor.Patch, como 1.0.0.
• Evitar caracteres especiales o espacios en los nombres de las etiquetas.
• Usar nombres descriptivos para etiquetas no relacionadas con versiones, como release-candidato, demo-presentación.

También se pueden firmar etiquetas para garantizar la integridad y autenticidad, utilizando una clave GPG:

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

Las etiquetas firmadas añaden una capa de seguridad al lanzamiento.

Para desplazarse a una etiqueta y ver el estado del proyecto en ese punto, se puede utilizar:

git checkout nombre_de_etiqueta

Esto situará el repositorio en un estado detached HEAD, por lo que se recomienda crear una rama si se quieren realizar cambios:

git checkout -b rama_a_partir_de_etiqueta nombre_de_etiqueta

Releases en GitHub: Cómo publicar versiones con changelogs

En GitHub, las releases sirven para empaquetar y publicar puntos específicos del historial del repositorio. Las releases están vinculadas a etiquetas (tags) y proporcionan un espacio donde los desarrolladores pueden compartir información detallada sobre una versión, incluyendo los changelogs, que son registros de cambios implementados.

Para publicar una release con changelog en GitHub, se sigue el proceso:

1. Acceder al repositorio en GitHub y seleccionar la pestaña "Releases" o navegar directamente a https://github.com/usuario/repositorio/releases.

2. Hacer clic en "Draft a new release" para iniciar la creación de una nueva release.

3. En el campo "Tag version", especificar el nombre de la etiqueta de la release. Si la etiqueta ya existe en el repositorio, se puede seleccionar de la lista; si no, GitHub creará una nueva etiqueta en este paso. Se suelen usar convenciones de versionado semántico, como v1.2.3.

4. En "Target", confirmar la rama o commit al que se vinculará la etiqueta. Por defecto, se selecciona la rama principal, pero se puede elegir cualquier punto del historial.

5. Añadir un título en el campo "Release title", que describa brevemente la versión, por ejemplo, "Lanzamiento de la versión 1.2.3".

6. En el área de "Descripción", escribir el changelog, detallando los cambios, mejoras y correcciones incluidos en esta versión. Se recomienda estructurar el changelog de manera organizada, utilizando secciones y listas.

Por ejemplo:

Nuevas características:

• Implementación del módulo de autenticación con OAuth2.
• Añadido soporte para notificaciones en tiempo real usando WebSockets.

Mejoras:

• Optimización de consultas a la base de datos para reducir tiempos de carga.
• Actualización de la interfaz de usuario con nuevos estilos y componentes.

Correcciones:

• Solucionado el error que impedía el registro de nuevos usuarios.
• Corregida la vulnerabilidad XSS en el formulario de comentarios.

7. Si se quiere, adjuntar archivos binarios o ejecutables asociados a la release, haciendo clic en "Attach binaries by dropping them here or selecting them". Esto se usa mucho en proyectos que distribuyen compilaciones o instaladores.

8. Opcionalmente, marcar la casilla "This is a pre-release" si se trata de una versión preliminar o versión beta. Esto ayuda a diferenciar entre versiones estables y aquellas en desarrollo.

9. Revisar la información y hacer clic en "Publish release" para publicar la release.

Las releases en GitHub ofrecen algunos beneficios como:

• Proporcionan a los usuarios un acceso sencillo a versiones específicas sin necesidad de clonar el repositorio completo.
• Facilitan la distribución de compilaciones y archivos asociados directamente desde GitHub.
• Mejoran la documentación y comunicación de cambios a través de changelogs detallados.

Buenas prácticas al publicar releases incluyen:

• Utilizar versionado semántico para asignar números de versión claros y significativos.
• Mantener los changelogs actualizados, reflejando con precisión los cambios realizados. Esto ayuda a usuarios y colaboradores a entender las evoluciones del proyecto.
• Referenciar issues y pull requests relevantes en el changelog, usando el formato #número, lo que crea enlaces automáticos y ayuda en la trazabilidad.

Por ejemplo:

• Correcciones:
  • Resuelto el problema de autenticación al expirar la sesión (#256).
  • Corregido el error de desbordamiento de búfer en el módulo de carga de archivos (#278).

Se puede automatizar parte del proceso de generación de changelogs con herramientas como Conventional Commits o Keep a Changelog, que estandarizan los mensajes de commit y hacen más fácil la recopilación de cambios.

Ejemplo de Release en GitHub en el repositorio de Angular: 

Además, las releases pueden integrarse con GitHub Actions para automatizar tareas como:

• Desplegar la aplicación a servidores o servicios en la nube tras la publicación de una release.
• Ejecutar pruebas automatizadas para validar la estabilidad de la versión.
• Notificar a los equipos o usuarios interesados mediante integraciones con sistemas de mensajería.

Para mantener un buen flujo de trabajo, es muy importante sincronizar las etiquetas locales con el repositorio remoto. Antes de crear una release en GitHub, asegurarse de haber empujado la etiqueta correspondiente:

git push origin v1.2.3

Esto se hace para garantizar que la release esté vinculada al estado exacto del código que se quiera publicar.

Versionado semántico (SemVer): Prácticas recomendadas para etiquetar versiones

El versionado semántico, conocido como SemVer, es un estándar muy usado para asignar números de versión que reflejen de forma clara los cambios en un proyecto.

El formato básico de SemVer es MAJOR.MINOR.PATCH, donde cada segmento tiene un significado específico:

• MAJOR (versión mayor): se incrementa cuando se realizan cambios incompatibles con versiones anteriores, es decir, cuando se introducen modificaciones que rompen la compatibilidad de la API o el comportamiento esperado.
• MINOR (versión menor): se incrementa al añadir nuevas funcionalidades de forma compatible con versiones anteriores. Estas adiciones no afectan a la compatibilidad existente.
• PATCH (parche): se incrementa al realizar correcciones de errores menores que no afectan a la API ni añaden funcionalidades nuevas.

Por ejemplo, una secuencia de versiones podría ser 1.0.0 ➔ 1.1.0 (nueva funcionalidad) ➔ 1.1.1 (corrección de errores).

Para etiquetar versiones en Git siguiendo SemVer, se recomienda utilizar el formato estándar, opcionalmente precedido por un prefijo como v. Por ejemplo:

git tag -a v2.3.0 -m "Lanzamiento de la versión 2.3.0 con mejoras en el rendimiento"

Es muy importante mantener una consistencia en la nomenclatura de las etiquetas. Si se decide utilizar el prefijo v, debe aplicarse en todas las versiones.

Además, SemVer tiene identificadores adicionales para versiones prelanzamiento y metadatos de compilación. Las versiones prelanzamiento se especifican añadiendo un guión y una etiqueta, como 1.2.0-beta.1, indicando que es una versión todavía en pruebas. Los metadatos de compilación se añaden con un signo más, por ejemplo, 1.2.0+exp.sha.5114f85.

Para etiquetar una versión preliminar en Git:

git tag -a v1.2.0-beta.1 -m "Versión beta 1 de la próxima versión 1.2.0"

Esto es útil para indicar que la versión aún está en desarrollo y puede no ser estable, haciendo que los usuarios puedan distinguir entre versiones finales y en pruebas.

Es aconsejable documentar los cambios en cada versión. Al crear una etiqueta anotada, se puede incluir un mensaje descriptivo que resuma las modificaciones:

git tag -a v1.2.0 -m "Añadida la funcionalidad de informes personalizado y optimizada la carga de datos"

El uso de SemVer en las etiquetas de Git mejora la compatibilidad con herramientas externas y sistemas de gestión de dependencias. Muchos administradores de paquetes, como npm o pip, utilizan el versionado semántico para gestionar las dependencias y garantizar que las actualizaciones se realicen sin conflictos.

Consejos adicionales para aplicar correctamente SemVer:

• Evitar incrementos de la versión mayor salvo que existan cambios que realmente rompan la compatibilidad. Esto ayuda a minimizar las actualizaciones disruptivas para los usuarios.
• Planificar cuidadosamente los cambios que afecten a la compatibilidad y considerar proporcionar guías de migración o documentación adicional.
• Utilizar incrementos en la versión de parche para distribuir correcciones rápidas sin introducir riesgos de incompatibilidad o cambios significativos en la funcionalidad.
• Involucrar al equipo en la decisión sobre el incremento de versiones, estableciendo una política clara que defina criterios para cada incremento.

En proyectos colaborativos, es útil establecer un flujo de trabajo que integre el versionado semántico con las prácticas de desarrollo. Esto puede incluir:

• Definir ramas para cada tipo de versión, como main para versiones estables y develop para desarrollo activo.
• Utilizar herramientas de integración continua que automaticen el etiquetado y despliegue basándose en las convenciones de SemVer.
• Implementar validaciones que aseguren la consistencia en los mensajes de commits y en las etiquetas creadas.

En el contexto de GitHub, combinar las etiquetas de Git con las releases hace más fácil la distribución de nuevas versiones.