Merge branch 'docs/release-process' into minor

# Conflicts:
#	Makefile
#	docs/website/src/content/docs/en/guides/release.md
#	sync-version-with-tag.sh

Author: yacosta738

Makefile

@@ -258,12 +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)
+sync-version: ## Sync VERSION in gradle.properties with the latest git tag (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
+        ci-test ci-check all quick sync-version

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

@@ -67,7 +67,7 @@ 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
+2) 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)

sync-version-with-tag.sh

@@ -4,8 +4,8 @@
 
 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)
+# Get the globally latest semantic version tag matching vX.Y.Z
+tag=$(git tag --sort=-v:refname | grep -Em1 '^v[0-9]+\.[0-9]+\.[0-9]+$' || true)
 if [[ -z "$tag" ]]; then
   echo "ERROR: No tag matching vX.Y.Z was found."
   exit 1
@@ -20,9 +20,13 @@ if [[ ! -f $prop_file ]]; then
   exit 1
 fi
 
-# Replace the VERSION=... line
-sed -i.bak -E "s/^VERSION=.*/VERSION=$version/" "$prop_file"
-rm -f "$prop_file.bak"
+# Update the VERSION= line or append if missing
+if grep -q '^VERSION=' "$prop_file"; then
+  sed -i.bak -E "s/^VERSION=.*/VERSION=$version/" "$prop_file"
+  rm -f "$prop_file.bak"
+else
+  echo "VERSION=$version" >> "$prop_file"
+fi
 
 echo "OK: gradle.properties updated to VERSION=$version"