Skip to content

Commit 7add99a

Browse files
yacosta738yacosta738
authored
feat(docs): add automation for syncing version from Git tag to gradle properties (#13) (#14)
* 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 * 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 * fix(docs): update sync-version script and documentation for clarity * fix(docs): improve sync-version script documentation and usage instructions
1 parent 6ebbc92 commit 7add99a

6 files changed

Lines changed: 144 additions & 15 deletions

File tree

‎Makefile‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -258,13 +258,12 @@ all: clean build check ## Run full CI pipeline (clean, build, check)
258258
quick: format build-fast ## Quick development cycle (format + build without tests)
259259
@echo "✨ Quick build completed!"
260260

261+
sync-version: ## Sync VERSION in gradle.properties with the latest git tag (vX.Y.Z)
262+
@bash ./sync-version-with-tag.sh
263+
261264
.PHONY: help check-tools setup wrapper build build-fast clean clean-all run dev \
262265
run-java run-kotlin run-spring test test-app test-coverage test-verbose \
263266
format check-format lint-kotlin lint-java lint check docs docs-serve \
264267
docs-web-build docs-web-check docs-web-format docs-web-dev \
265268
deps deps-app deps-analysis deps-update tasks info version ci-build \
266-
ci-test ci-check all quick
267-
268-
# ====================================================================================
269-
# END OF MAKEFILE
270-
# ====================================================================================
269+
ci-test ci-check all quick sync-version

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,6 @@ make test
4343

4444
## Next Steps
4545

46-
- Explore the [Project Structure](../structure/) to understand how files are organized.
47-
- Check the [Features Checklist](../features/) for available functionalities.
48-
- Learn about standard [Development Procedures](../development/).
46+
- Explore the [Project Structure](./structure/) to understand how files are organized.
47+
- Check the [Features Checklist](./features/) for available functionalities.
48+
- Learn about standard [Development Procedures](./development/).

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

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This guide explains how to publish releases and snapshots to Maven Central using
88

99
Before you can publish, ensure you have:
1010

11-
1. **GPG Key configured**: Follow the [GPG Setup Guide](../gpg-setup/) to create and configure your signing key
11+
1. **GPG Key configured**: Follow the [GPG Setup Guide](./gpg-setup/) to create and configure your signing key
1212
2. **Maven Central access**: Repository secrets configured:
1313
- `SIGNING_IN_MEMORY_KEY`: Your GPG private key
1414
- `SIGNING_IN_MEMORY_KEY_PASSWORD`: GPG key passphrase
@@ -43,6 +43,50 @@ version = "1.2.3" // For patch releases
4343
version = "1.3.0" // For minor releases
4444
```
4545

46+
### Automating version sync from Git tag
47+
48+
You can keep the project version in sync with a Git tag automatically using the helper script and Make target included in this repository.
49+
50+
- `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`.
51+
- `./sync-version-with-tag.sh` — shell script that selects the globally latest semantic tag using `git tag --sort=-v:refname | grep -Em1 '^v[0-9]+\.[0-9]+\.[0-9]+$'` (not the nearest tag from `HEAD`), extracts the numeric version (drops the leading `v`), and replaces the `VERSION=` line in `gradle.properties`.
52+
53+
Usage patterns (pick one workflow):
54+
55+
1) Recommended (update code first, then tag)
56+
57+
```bash
58+
# Update build files and commit
59+
# bump version in gradle.properties or build.gradle.kts to 0.1.1
60+
git add gradle.properties
61+
git commit -m "chore: bump version to 0.1.1"
62+
63+
# Create an annotated tag matching the version
64+
git tag -a v0.1.1 -m "Release v0.1.1"
65+
# Push commit and tag
66+
git push origin main
67+
git push origin v0.1.1
68+
```
69+
70+
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
71+
72+
```bash
73+
# Ensure tag exists locally (or fetch it)
74+
git fetch --tags
75+
76+
# Sync gradle.properties to the latest tag
77+
make sync-version
78+
# Review and commit the change
79+
git add gradle.properties
80+
git commit -m "chore: sync version to $(awk -F= '/^VERSION=/{print $2; exit}' gradle.properties)"
81+
# Push the commit (no need to recreate the tag)
82+
git push origin main
83+
```
84+
85+
Notes and caveats:
86+
- 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)".
87+
- Prefer creating the commit that updates the version before creating the tag to avoid mismatches.
88+
- The script only recognizes tags matching the regex `^v[0-9]+\.[0-9]+\.[0-9]+$`.
89+
4690
### Step 3: Create and push a tag
4791

4892
```bash
@@ -127,6 +171,6 @@ Use this checklist before publishing:
127171

128172
## See Also
129173

130-
- [GPG Setup Guide](../gpg-setup/)
174+
- [GPG Setup Guide](./gpg-setup/)
131175
- [GitHub Workflows](https://github.com/dallay/starter-gradle/blob/main/.github/workflows/README.md)
132176
- [Contributing Guide](https://github.com/dallay/starter-gradle/blob/main/.github/CONTRIBUTING.md)

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,6 @@ make test
4848

4949
## Siguientes Pasos
5050

51-
- Explora la [Estructura del Proyecto](../structure/) para entender cómo están organizados los archivos.
52-
- Consulta la [Lista de Funcionalidades](../features/) para conocer las capacidades disponibles.
53-
- Aprende sobre los [Procedimientos de Desarrollo](../development/) estándar.
51+
- Explora la [Estructura del Proyecto](./structure/) para entender cómo están organizados los archivos.
52+
- Consulta la [Lista de Funcionalidades](./features/) para conocer las capacidades disponibles.
53+
- Aprende sobre los [Procedimientos de Desarrollo](./development/) estándar.

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

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Esta guía explica cómo publicar releases y snapshots en Maven Central usando G
88

99
Antes de poder publicar, asegúrate de tener:
1010

11-
1. **Clave GPG configurada**: Sigue la [Guía de Configuración GPG](../gpg-setup/) para crear y configurar tu clave de firma
11+
1. **Clave GPG configurada**: Sigue la [Guía de Configuración GPG](./gpg-setup/) para crear y configurar tu clave de firma
1212
2. **Acceso a Maven Central**: Secrets del repositorio configurados:
1313
- `SIGNING_IN_MEMORY_KEY`: Tu clave privada GPG
1414
- `SIGNING_IN_MEMORY_KEY_PASSWORD`: Contraseña de la clave GPG
@@ -43,6 +43,50 @@ version = "1.2.3" // Para releases de patch
4343
version = "1.3.0" // Para releases minor
4444
```
4545

46+
### Sincronizar la versión desde el tag Git automáticamente
47+
48+
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.
49+
50+
- `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`.
51+
- `./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`.
52+
53+
Flujos de uso (elige uno):
54+
55+
1) Recomendado (actualiza el código primero, luego el tag)
56+
57+
```bash
58+
# Actualiza los archivos de build y commitea
59+
# incrementar version en gradle.properties o build.gradle.kts a 0.1.1
60+
git add gradle.properties
61+
git commit -m "chore: bump version to 0.1.1"
62+
63+
# Crear un tag anotado que coincida con la version
64+
git tag -a v0.1.1 -m "Release v0.1.1"
65+
# Pushear commit y tag
66+
git push origin main
67+
git push origin v0.1.1
68+
```
69+
70+
2) Si creaste el tag primero (causa del fallo en CI), sincroniza el código con el tag localmente y commitea el cambio
71+
72+
```bash
73+
# Asegúrate de tener el tag localmente (o fetch)
74+
git fetch --tags
75+
76+
# Sincronizar gradle.properties con el último tag
77+
make sync-version
78+
# Revisar y commitear el cambio
79+
git add gradle.properties
80+
git commit -m "chore: sync version to $(git describe --tags --abbrev=0 | sed 's/^v//')"
81+
# Pushear el commit (no es necesario recrear el tag)
82+
git push origin main
83+
```
84+
85+
Notas y advertencias:
86+
- 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)".
87+
- Es preferible crear el commit que actualiza la versión antes de crear el tag para evitar desajustes.
88+
- El script solo reconoce tags que cumplen la expresión `^v[0-9]+\.[0-9]+\.[0-9]+$`.
89+
4690
### Paso 3: Crear y pushear un tag
4791

4892
```bash
@@ -127,6 +171,6 @@ Usa este checklist antes de publicar:
127171

128172
## Ver También
129173

130-
- [Guía de Configuración GPG](../gpg-setup/)
174+
- [Guía de Configuración GPG](./gpg-setup/)
131175
- [GitHub Workflows](https://github.com/dallay/starter-gradle/blob/main/.github/workflows/README.md)
132176
- [Guía de Contribución](https://github.com/dallay/starter-gradle/blob/main/.github/CONTRIBUTING.md)

‎sync-version-with-tag.sh‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/bin/bash
2+
# sync-version-with-tag.sh
3+
# Update the version in gradle.properties to match the latest Git tag (vX.Y.Z)
4+
5+
set -euo pipefail
6+
7+
# Get the globally latest semantic version tag matching vX.Y.Z
8+
tag=$(git tag --sort=-v:refname | grep -Em1 '^v[0-9]+\.[0-9]+\.[0-9]+$' || true)
9+
if [[ -z "$tag" ]]; then
10+
echo "ERROR: No tag matching vX.Y.Z was found."
11+
exit 1
12+
fi
13+
14+
version="${tag#v}"
15+
echo "Syncing VERSION in gradle.properties to: $version"
16+
17+
prop_file="gradle.properties"
18+
if [[ ! -f $prop_file ]]; then
19+
echo "ERROR: $prop_file not found"
20+
exit 1
21+
fi
22+
23+
# Update the VERSION= line or append if missing
24+
if grep -q '^VERSION=' "$prop_file"; then
25+
sed -i.bak -E "s/^VERSION=.*/VERSION=$version/" "$prop_file"
26+
rm -f "$prop_file.bak"
27+
else
28+
echo "VERSION=$version" >> "$prop_file"
29+
fi
30+
31+
echo "OK: gradle.properties updated to VERSION=$version"
32+
33+
# Helpful next-steps message
34+
cat <<EOF
35+
Next steps (recommended):
36+
1) Review the change: git diff $prop_file
37+
2) Commit the change: git add $prop_file && git commit -m "chore: sync version to $version"
38+
3) Push your branch and tag as appropriate.
39+
If tag v$version already exists but points at the wrong commit, prefer creating a new patch version.
40+
Only force-update a tag after confirming no one else depends on it and with explicit confirmation.
41+
See "Version already exists" troubleshooting guidance in docs/website/src/content/docs/en/guides/release.md.
42+
EOF

0 commit comments

Comments
 (0)