---
name: xberg-io/release-versioning
source: https://app.decimal.ai/s/xberg-io-release-versioning@1/SKILL.md
source_sha256: f6b12b6a8c20
---

# Release & Versioning

## Single source of truth

The root `Cargo.toml` `version` is the one authoritative version (including any
`-rc.N` pre-release suffix). Everything else is derived from it — never hand-edit
a version in a package manifest.

## `task version:sync` propagates to two families

`task version:sync` (alias `task versions:sync`) runs, in order:

1. `alef sync-versions` — updates the **alef-managed binding manifests** (their own
   version = core version). Targets are listed in `alef.toml` `[workspace.sync] extra_paths`
   (packages/python, packages/ruby, crates/xberg-node, packages/go, cli-proxy, …).
2. `python3 scripts/sync_integration_versions.py` — updates the **integrations**
   under `integrations/`. These are NOT alef-managed, so alef never touches them.

Bump/set helpers chain both automatically:
`task version:bump:major|minor|patch`, `task version:set -- <version>`.
`task version:check` dry-runs both and fails on drift (`sync_integration_versions.py --check`).

## Integrations are lockstep with core

The integration packages under `integrations/` are versioned and **published together
with core** across three ecosystems:

- **Python → PyPI**: langchain, llama-index (readers + node-parser), crewai, txtai, surrealdb.
- **Java → Maven Central**: spring-ai (`io.xberg:spring-ai-xberg`).
- **npm → npm**: n8n-nodes-xberg, langchain-xberg, llamaindex-xberg (`@xberg-io/*`).

`scripts/sync_integration_versions.py` sets, for each manifest:

- the package's own `version` — PEP 440 form for pyproject (`1.0.0-rc.32` → `1.0.0rc32`),
  native form for the Maven pom and npm `package.json` (`1.0.0-rc.32`, also valid semver);
- the `xberg` dependency pin, so an integration always requires the core it ships with:
  - pyproject: a **floor** `xberg>=<core>` (PEP 440 form). Naming the rc is deliberate —
    a bare `xberg>=1.0.0` excludes all `1.0.0rcN` pre-releases per PEP 440.
  - pom: `<xberg.version>` (native form).
  - npm `package.json`: an **exact** `@xberg-io/xberg` pin (native/semver form), matching
    the package's own version.

To add a new integration: add its manifest to `VERSION_TARGETS` (own version) and, if it
depends on xberg, `XBERG_DEP_MANIFESTS` in `scripts/sync_integration_versions.py`
(npm `package.json` manifests are collected in `NPM_MANIFESTS`, which feeds both lists).
The llama-index dev aggregator (`integrations/python/llama-index/pyproject.toml`, version
`0.0.0`, unpublished) is dep-only — not a version target.

## Do

- Bump via `task version:bump:*` / `task version:set`, then commit the synced manifests
  together with the Cargo.toml change (atomic).
- Run `task version:check` in CI to guarantee integration manifests never drift from core.

## Don't

- Don't hand-edit a package/manifest version or an integration's `xberg` pin — run the sync.
- Don't add integration manifests to `alef.toml` `[workspace.sync]` — alef would clobber
  their independent-but-derived layout; the dedicated script owns them.