Versionierung

Selu verwendet semantische Versionierung, also SemVer, für Agentenpakete. Saubere Versionen helfen Nutzern zu verstehen, was sich geändert hat, und erlauben dem Orchestrator, Upgrades sicher zu behandeln.

Versionsformat

Versionen folgen dem Muster MAJOR.MINOR.PATCH:

1.0.0
│ │ └── PATCH: bug fixes, prompt tweaks, no behaviour change
│ └──── MINOR: new features, new capabilities, backward-compatible
└────── MAJOR: breaking changes (removed capabilities, changed routing, new required credentials)

Das Feld version in agent.yaml ist die einzige Quelle der Wahrheit:

agent.yaml

version: 1.2.3

Was gilt als Breaking Change?

Ein Major-Versionssprung ist nötig, wenn:

• eine Capability entfernt oder umbenannt wird
• sich erforderliche Umgebungsvariablen ändern, etwa eine neue Pflicht-Credential oder ein umbenannter Variablenname
• sich Routing-Regeln so ändern, dass der Agent in anderen Situationen aktiviert wird
• sich der Kernzweck des Agenten deutlich verändert

Ein Minor-Versionssprung ist passend, wenn:

• eine neue Capability hinzukommt
• neue optionale Funktionen oder Konfigurationsmöglichkeiten eingeführt werden
• der System Prompt deutlich verbessert wird, der Zweck des Agenten aber gleich bleibt

Ein Patch-Versionssprung deckt ab:

• Fehlerbehebungen in Capabilities
• kleinere Prompt-Anpassungen für bessere Genauigkeit
• Abhängigkeitsupdates ohne Verhaltensänderung

Tipp

Wenn du unsicher bist, erhöhe lieber Minor. Nutzer können bei Bedarf immer auf eine feste Version pinnen.

Upgrade-Richtlinien

Wenn eine neue Version eines installierten Agenten veröffentlicht wird, prüft der Orchestrator die Upgrade-Richtlinie des Nutzers:

Richtlinie	Verhalten
auto-patch (Standard)	Patch-Updates werden automatisch installiert. Minor und Major brauchen Bestätigung.
auto-minor	Patch- und Minor-Updates werden automatisch installiert. Major braucht Bestätigung.
manual	Jedes Update braucht eine ausdrückliche Bestätigung des Nutzers.
pin	Nie aktualisieren. Der Nutzer bleibt auf der installierten Version.

Nutzer konfigurieren das pro Agent in ihren Selu-Einstellungen.

Versions-Constraints in agent.yaml

Wenn dein Agent eine entfernte Capability per Image referenziert, solltest du die Version pinnen:

agent.yaml

capabilities:
  - name: weather
    image: registry.selu.bot/selu-examples/weather:^1.0.0

Unterstützte Constraint-Syntax:

Syntax	Bedeutung
1.2.3	Exakte Version
^1.2.0	Kompatibel mit 1.x.x (>= 1.2.0, < 2.0.0)
~1.2.0	Nur Änderungen auf Patch-Ebene (>= 1.2.0, < 1.3.0)
>=1.0.0	Jede Version ab 1.0.0

Pre-Release-Versionen

Zum Testen vor einem stabilen Release kannst du Pre-Release-Tags verwenden:

version: 2.0.0-beta.1

Pre-Release-Versionen werden nie automatisch installiert. Nutzer müssen sie ausdrücklich aktivieren. Im Marketplace erscheinen sie mit einem Beta-Badge.

Hinweis

Im Marketplace wird standardmäßig nur die neueste stabile Version angezeigt. Pre-Release-Versionen sind im Dropdown des Versionsverlaufs sichtbar.

Changelogs

Auch wenn es nicht zwingend vorgeschrieben ist, wird eine CHANGELOG.md in deinem Agenten-Repository dringend empfohlen. Der Marketplace zeigt sie neben dem Versionsverlauf an, wenn sie vorhanden ist.

Empfohlen wird das Format von Keep a Changelog:

CHANGELOG.md

## [1.2.0] - 2025-07-15
### Added
- Forecast capability for 7-day weather predictions.

### Fixed
- Improved location parsing for ambiguous city names.

Nächste Schritte

• Release Pipeline: Versionserhöhungen und Veröffentlichung automatisieren
• Marketplace-Richtlinien: Anforderungen für die Einreichung