VelesDB Release Process

Guide simplifié pour publier une nouvelle version de VelesDB.

Architecture des Workflows

VelesDB utilise 3 workflows GitHub Actions :

Workflow	Trigger	Fonction
ci.yml	Push/PR sur main	Tests, lint, security audit
release.yml	Tag v*	Publication complète
bench-regression.yml	Push sur main	Benchmarks de régression

Publier une Release

1. Bump version (automatisé)

# Apply the bump to every policed manifest (X.Y.Z = target release version)
python3 scripts/bump_version.py X.Y.Z
# Regenerate the OpenAPI snapshots (derived from the crate version)
cargo test -p velesdb-server --features openapi generate_openapi_spec_files -- --test-threads=1
cargo build  # refresh Cargo.lock
python3 scripts/check-version-sync.py  # must report: All versions match

Le script bump_version.py met à jour automatiquement :

• Cargo.toml (workspace)
• sdks/typescript/package.json
• crates/velesdb-python/pyproject.toml
• crates/velesdb-wasm/pkg/package.json
• crates/tauri-plugin-velesdb/guest-js/package.json
• integrations/langchain/pyproject.toml
• integrations/llamaindex/pyproject.toml
• demos/rag-pdf-demo/pyproject.toml

2. Mettre à jour CHANGELOG.md

Ajouter une section pour la nouvelle version avec les changements.

3. Commit et push (SANS tag)

git add -A
git commit -m "chore(release): bump version to X.Y.Z"
git push origin main

4. Attendre que le CI passe sur main

Le CI (ci.yml) valide le commit de release : tests, lint, security, conformance, perf smoke. Ne pas créer le tag tant que le CI n'est pas vert.

# Surveiller le CI
gh run watch $(gh run list --branch main --limit 1 --json databaseId --jq '.[0].databaseId')

Si le CI échoue, corriger et re-pusher. Aucun tag n'existe donc aucun rollback de version n'est nécessaire.

5. Créer et pusher le tag (après CI vert)

git tag -a vX.Y.Z -m "vX.Y.Z - Description"
git push origin vX.Y.Z

6. Le workflow release.yml publie automatiquement

Destination	Package
GitHub Release	Binaries Linux/Windows/macOS + .deb
crates.io	velesdb-core, velesdb-cli, velesdb-server, velesdb-migrate, velesdb-mobile, tauri-plugin-velesdb
crates.io (independent velesdb-memory-v* tag)	velesdb-memory (0.1.0 cadence, via release-memory.yml)
PyPI	velesdb
npm	@wiscale/velesdb-wasm, @wiscale/velesdb-sdk, @wiscale/velesdb-memory-node (napi prebuilds; publish job TBD, see note)

7. Vérifier le déploiement

• GitHub Actions : https://github.com/cyberlife-coder/VelesDB/actions
• GitHub Releases : https://github.com/cyberlife-coder/VelesDB/releases
• crates.io : https://crates.io/crates/velesdb-core
• PyPI : https://pypi.org/project/velesdb/
• npm : https://www.npmjs.com/package/@wiscale/velesdb-wasm

Pre-releases

Pour une pre-release (beta, rc) :

git tag vX.Y.Z-beta.1
git push origin vX.Y.Z-beta.1

Le workflow détecte automatiquement les pre-releases et :

• Crée une GitHub Release marquée "Pre-release"
• Ne publie PAS sur crates.io/PyPI/npm

Secrets requis

Secret	Usage
CARGO_REGISTRY_TOKEN	Publication crates.io
NPM_TOKEN	Publication npm
PYPI_API_TOKEN	Publication PyPI (ou trusted publishing)

Dépannage

Le workflow ne se déclenche pas

Vérifier que le tag suit le format v[0-9]+.[0-9]+.[0-9]+ :

• ✅ vX.Y.Z
• ✅ vX.Y.Z-beta.1
• ❌ X.Y.Z (pas de "v")
• ❌ vX.Y (version incomplète)

Publication déjà existante

Si une version existe déjà sur crates.io/PyPI/npm, le workflow skip cette étape avec un message ⏭️ already published.

Force-update un tag

git tag -d vX.Y.Z
git tag vX.Y.Z
git push origin vX.Y.Z --force

Workflow manuel

Pour déclencher manuellement une release sans tag :

1. Aller sur GitHub Actions
2. Sélectionner "Release"
3. Cliquer "Run workflow"
4. Entrer la version (ex: 0.8.6)