feat(docs): add automation for syncing version from Git tag to gradle properties (#13)

* feat(docs): add automation for syncing version from Git tag to gradle.properties

* fix(docs): corregir enlaces relativos en guías para pasar lychee

* fix(docs): correct step numbering in release process documentation

Author: yacosta738

Makefile

@@ -258,13 +258,12 @@ all: clean build check ## Run full CI pipeline (clean, build, check)
 quick: format build-fast ## Quick development cycle (format + build without tests)
 	@echo "✨ Quick build completed!"
 
+sync-version: ## Sincroniza VERSION en gradle.properties con el último tag git (vX.Y.Z)
+	@bash ./sync-version-with-tag.sh
+
 .PHONY: help check-tools setup wrapper build build-fast clean clean-all run dev \
         run-java run-kotlin run-spring test test-app test-coverage test-verbose \
         format check-format lint-kotlin lint-java lint check docs docs-serve \
         docs-web-build docs-web-check docs-web-format docs-web-dev \
         deps deps-app deps-analysis deps-update tasks info version ci-build \
         ci-test ci-check all quick
-
-# ====================================================================================
-# END OF MAKEFILE
-# ====================================================================================

docs/website/src/content/docs/en/guides/getting-started.md

@@ -43,6 +43,6 @@ make test
 
 ## Next Steps
 
-- Explore the [Project Structure](../structure/) to understand how files are organized.
-- Check the [Features Checklist](../features/) for available functionalities.
-- Learn about standard [Development Procedures](../development/).
+- Explore the [Project Structure](./structure/) to understand how files are organized.
+- Check the [Features Checklist](./features/) for available functionalities.
+- Learn about standard [Development Procedures](./development/).

docs/website/src/content/docs/en/guides/release.md

@@ -8,7 +8,7 @@ This guide explains how to publish releases and snapshots to Maven Central using
 
 Before you can publish, ensure you have:
 
-1. **GPG Key configured**: Follow the [GPG Setup Guide](../gpg-setup/) to create and configure your signing key
+1. **GPG Key configured**: Follow the [GPG Setup Guide](./gpg-setup/) to create and configure your signing key
 2. **Maven Central access**: Repository secrets configured:
    - `SIGNING_IN_MEMORY_KEY`: Your GPG private key
    - `SIGNING_IN_MEMORY_KEY_PASSWORD`: GPG key passphrase
@@ -43,6 +43,50 @@ version = "1.2.3"  // For patch releases
 version = "1.3.0"  // For minor releases
 ```
 
+### Automating version sync from Git tag
+
+You can keep the project version in sync with a Git tag automatically using the helper script and Make target included in this repository.
+
+- `make sync-version` — runs `./sync-version-with-tag.sh` and updates `gradle.properties` so `VERSION=` matches the latest Git tag of the form `vX.Y.Z`.
+- `./sync-version-with-tag.sh` — shell script that reads the latest tag (`git describe --tags --abbrev=0`), extracts the numeric version (drops the leading `v`), and replaces the `VERSION=` line in `gradle.properties`.
+
+Usage patterns (pick one workflow):
+
+1) Recommended (update code first, then tag)
+
+```bash
+# Update build files and commit
+# bump version in gradle.properties or build.gradle.kts to 0.1.1
+git add gradle.properties
+git commit -m "chore: bump version to 0.1.1"
+
+# Create an annotated tag matching the version
+git tag -a v0.1.1 -m "Release v0.1.1"
+# Push commit and tag
+git push origin main
+git push origin v0.1.1
+```
+
+1) If you created the tag first (what caused the CI failure you saw), sync the code to the tag locally and commit the change
+
+```bash
+# Ensure tag exists locally (or fetch it)
+git fetch --tags
+
+# Sync gradle.properties to the latest tag
+make sync-version
+# Review and commit the change
+git add gradle.properties
+git commit -m "chore: sync version to $(git describe --tags --abbrev=0 | sed 's/^v//')"
+# Push the commit (no need to recreate the tag)
+git push origin main
+```
+
+Notes and caveats:
+- The repository’s release CI enforces that the Git tag (e.g. `v0.1.1`) matches the code version (e.g. `0.1.1`). If they don't match the build fails with an error like: "CI Release: GitHub tag (v0.1.1) must match Code version (0.1.0)".
+- Prefer creating the commit that updates the version before creating the tag to avoid mismatches.
+- The script only recognizes tags matching the regex `^v[0-9]+\.[0-9]+\.[0-9]+$`.
+
 ### Step 3: Create and push a tag
 
 ```bash
@@ -127,6 +171,6 @@ Use this checklist before publishing:
 
 ## See Also
 
-- [GPG Setup Guide](../gpg-setup/)
+- [GPG Setup Guide](./gpg-setup/)
 - [GitHub Workflows](https://github.com/dallay/starter-gradle/blob/main/.github/workflows/README.md)
 - [Contributing Guide](https://github.com/dallay/starter-gradle/blob/main/.github/CONTRIBUTING.md)

docs/website/src/content/docs/es/guides/getting-started.md

@@ -48,6 +48,6 @@ make test
 
 ## Siguientes Pasos
 
-- Explora la [Estructura del Proyecto](../structure/) para entender cómo están organizados los archivos.
-- Consulta la [Lista de Funcionalidades](../features/) para conocer las capacidades disponibles.
-- Aprende sobre los [Procedimientos de Desarrollo](../development/) estándar.
+- Explora la [Estructura del Proyecto](./structure/) para entender cómo están organizados los archivos.
+- Consulta la [Lista de Funcionalidades](./features/) para conocer las capacidades disponibles.
+- Aprende sobre los [Procedimientos de Desarrollo](./development/) estándar.

docs/website/src/content/docs/es/guides/release.md

@@ -8,7 +8,7 @@ Esta guía explica cómo publicar releases y snapshots en Maven Central usando G
 
 Antes de poder publicar, asegúrate de tener:
 
-1. **Clave GPG configurada**: Sigue la [Guía de Configuración GPG](../gpg-setup/) para crear y configurar tu clave de firma
+1. **Clave GPG configurada**: Sigue la [Guía de Configuración GPG](./gpg-setup/) para crear y configurar tu clave de firma
 2. **Acceso a Maven Central**: Secrets del repositorio configurados:
    - `SIGNING_IN_MEMORY_KEY`: Tu clave privada GPG
    - `SIGNING_IN_MEMORY_KEY_PASSWORD`: Contraseña de la clave GPG
@@ -43,6 +43,50 @@ version = "1.2.3"  // Para releases de patch
 version = "1.3.0"  // Para releases minor
 ```
 
+### Sincronizar la versión desde el tag Git automáticamente
+
+Puedes mantener la versión del proyecto en sincronía con el tag Git automáticamente con el script y el target Make incluidos en este repositorio.
+
+- `make sync-version` — ejecuta `./sync-version-with-tag.sh` y actualiza `gradle.properties` para que `VERSION=` coincida con el último tag Git con formato `vX.Y.Z`.
+- `./sync-version-with-tag.sh` — script que lee el último tag (`git describe --tags --abbrev=0`), extrae la versión numérica (quita la `v` inicial) y reemplaza la línea `VERSION=` en `gradle.properties`.
+
+Flujos de uso (elige uno):
+
+1) Recomendado (actualiza el código primero, luego el tag)
+
+```bash
+# Actualiza los archivos de build y commitea
+# incrementar version en gradle.properties o build.gradle.kts a 0.1.1
+git add gradle.properties
+git commit -m "chore: bump version to 0.1.1"
+
+# Crear un tag anotado que coincida con la version
+git tag -a v0.1.1 -m "Release v0.1.1"
+# Pushear commit y tag
+git push origin main
+git push origin v0.1.1
+```
+
+2) Si creaste el tag primero (causa del fallo en CI), sincroniza el código con el tag localmente y commitea el cambio
+
+```bash
+# Asegúrate de tener el tag localmente (o fetch)
+git fetch --tags
+
+# Sincronizar gradle.properties con el último tag
+make sync-version
+# Revisar y commitear el cambio
+git add gradle.properties
+git commit -m "chore: sync version to $(git describe --tags --abbrev=0 | sed 's/^v//')"
+# Pushear el commit (no es necesario recrear el tag)
+git push origin main
+```
+
+Notas y advertencias:
+- El CI de release exige que el tag Git (ej. `v0.1.1`) coincida con la versión en el código (ej. `0.1.1`). Si no coinciden, el build falla con un error como: "CI Release: GitHub tag (v0.1.1) must match Code version (0.1.0)".
+- Es preferible crear el commit que actualiza la versión antes de crear el tag para evitar desajustes.
+- El script solo reconoce tags que cumplen la expresión `^v[0-9]+\.[0-9]+\.[0-9]+$`.
+
 ### Paso 3: Crear y pushear un tag
 
 ```bash
@@ -127,6 +171,6 @@ Usa este checklist antes de publicar:
 
 ## Ver También
 
-- [Guía de Configuración GPG](../gpg-setup/)
+- [Guía de Configuración GPG](./gpg-setup/)
 - [GitHub Workflows](https://github.com/dallay/starter-gradle/blob/main/.github/workflows/README.md)
 - [Guía de Contribución](https://github.com/dallay/starter-gradle/blob/main/.github/CONTRIBUTING.md)

sync-version-with-tag.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# sync-version-with-tag.sh
+# Update the version in gradle.properties to match the latest Git tag (vX.Y.Z)
+
+set -euo pipefail
+
+# Get the latest tag matching vX.Y.Z
+tag=$(git describe --tags --abbrev=0 | grep -Eo '^v[0-9]+\.[0-9]+\.[0-9]+$' || true)
+if [[ -z "$tag" ]]; then
+  echo "ERROR: No tag matching vX.Y.Z was found."
+  exit 1
+fi
+
+version="${tag#v}"
+echo "Syncing VERSION in gradle.properties to: $version"
+
+prop_file="gradle.properties"
+if [[ ! -f $prop_file ]]; then
+  echo "ERROR: $prop_file not found"
+  exit 1
+fi
+
+# Replace the VERSION=... line
+sed -i.bak -E "s/^VERSION=.*/VERSION=$version/" "$prop_file"
+rm -f "$prop_file.bak"
+
+echo "OK: gradle.properties updated to VERSION=$version"
+
+# Helpful next-steps message
+cat <<EOF
+Next steps (recommended):
+  1) Review the change: git diff $prop_file
+  2) Commit the change: git add $prop_file && git commit -m "chore: sync version to $version"
+  3) Push your branch and tag as appropriate. Note: if you created the tag before committing this change, update the tag to point to the commit you want (git tag -f v$version) and push with --force if necessary.
+EOF