---
name: xberg-io-xberg-release
description: "Prepare Xberg releases: version sync, generated bindings, chart and CI gates."
license: "MIT"
metadata:
  decimalai-skill-id: "82227f3c-71f9-4b5f-b3be-a11537d5226f"
  decimalai-version-id: "6e95cb8a-bf87-4368-90e8-0f6bfef7f968"
  decimalai-version: "1"
  decimalai-body-sha256: "b00112145bb1d62b9b9c0647dd1e193e3d6df15cb90cd9a910a6247b3530ab55"
  decimalai-name: "xberg-io/xberg-release"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "devops"
  decimalai-source: "https://app.decimal.ai/s/xberg-io-xberg-release@1/SKILL.md"
---
# Xberg release

Repo specifics for the shared `release-workflow` skill: how the version propagates, and the readiness gate before a
push or release.

## Versioning

### Single source of truth

The root `Cargo.toml` `[workspace.package] 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.

### `mise run version:sync` runs three steps

`mise run version:sync` runs, in order
(`mise.toml`):

1. `alef sync-versions` — 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` — the **integrations** under
   `integrations/`, the Helm chart, and `plugin/.ai-rulez/config.plugins.toml` `[plugin].version`.
   These are NOT alef-managed, so alef never touches them.
3. `mise run plugin:generate` — `ai-rulez generate --plugin` (bundles under `plugin/`) plus
   `scripts/sync_public_skills.py` (root `skills/`). CI Lint fails on drift in either
   (`mise run plugin:verify`).

Bump/set helpers chain both automatically:
`mise run version:bump:major|minor|patch`.
`mise run version:check` prints the Cargo version and runs `sync_integration_versions.py --check`,
failing on integration drift. It does not dry-run `alef sync-versions`.

### Integrations are lockstep with core

The integration packages under `integrations/` are versioned and **published together
with core** across four target families:

- **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/*`).
- **Helm → chart**: `charts/xberg/Chart.yaml` (`version`, `appVersion`, the ArtifactHub image
  tag and prerelease flag) plus `charts/xberg/README.md`'s `--version`.

`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 `mise run version:bump:*`, then commit the synced manifests
  together with the Cargo.toml change (atomic).

### 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.

## Readiness

A release-ready commit is one for which CI, the Publish Release dry run, and Benchmarks complete successfully on the
same pushed SHA. A successful older run does not validate newer local commits.

### Audit

1. Check actual workflow failures; distinguish failures from cancellations, skipped jobs, and runs superseded by a
   newer SHA.
2. Map each failed job to a verified local fix or an explicit unresolved blocker. Do not infer that one similarly
   named fix covers a different job.
3. Verify generated Alef output is clean and reproducible with the version pinned in `alef.toml`; generated freshness
   failures remain unresolved until regeneration converges.
4. Keep the Unreleased changelog user-facing and synchronized with docs copies. Do not add CI, test, generator,
   dependency, or internal implementation notes unless users are affected.
5. Run targeted local checks for changed behavior plus the repository's formatting and linting tasks. Do not
   substitute a broad passing suite for a failed job's exact configuration.

### Publish dry-run contracts

- Helm `appVersion`, the container tag, and every `artifacthub.io/images` entry must describe an image that exists
  in GHCR. A chart package that names a missing compatibility tag causes Artifact Hub scan failures even when the
  chart itself published successfully.
- Linux native-library verification must reject unreadable binaries and GLIBC imports above the supported floor.
  A readable native library with no `GLIBC_*` imports is valid; it is not evidence that the scan failed.
- Windows artifact verification must evaluate each DLL independently. Reset per-library status before inspecting
  the next artifact so one result cannot leak into another.
- Elixir musl smoke tests need the NIF and the directory containing its bundled native libraries. Passing only the
  NIF path is insufficient when dependent shared libraries are staged beside it.
- Windows GNU Ruby builds must use the ORT-free feature set because the GNU ABI has no compatible ORT prebuilt.
- Scoop (shared `scoop-distribution` skill): `xberg.exe` imports `onnxruntime.dll`, so the publish job must vendor
  the DLL closure into the zip; the shim resolves DLLs from the app directory and no `depends` entry is needed.
  Tesseract is looked up on `PATH` at runtime and belongs in the manifest's `notes`, not `depends`.

### Push and dispatch

- Push one coherent state. Do not repeatedly push while intentional CI is still running merely to get newer diagnostics.
- After the push, dispatch CI, Publish Release with dry-run inputs, and Benchmarks against that pushed SHA.
- Retry only after identifying and addressing the cause. Cancellation alone is not a defect; a repeated actual
  failure is.
- Close addressed issues only after the fixing commit is reachable remotely, and state the intended release when
  requested.