Versioning

Selu uses semantic versioning (semver) for agent packages. Correct versioning helps users understand what changed and lets the orchestrator handle upgrades safely.

Version format

Versions follow the MAJOR.MINOR.PATCH pattern:

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)

The version field in agent.yaml is the single source of truth:

agent.yaml

version: 1.2.3

What counts as a breaking change?

A major version bump is required when:

• A capability is removed or renamed.
• Required environment variables change (new required credential, renamed variable).
• Routing rules change in a way that alters when the agent is activated.
• The agent’s core purpose changes significantly.

A minor version bump is appropriate when:

• A new capability is added.
• New optional features or configuration options are introduced.
• The system prompt is significantly improved (but the agent’s purpose stays the same).

A patch version bump covers:

• Bug fixes in capabilities.
• Minor prompt tweaks for better accuracy.
• Dependency updates that don’t change behaviour.

Tip

When in doubt, bump minor. Users can always pin to a specific version if they’re worried about changes.

Upgrade policies

When a new version of an installed agent is published, the orchestrator checks the user’s upgrade policy:

Policy	Behaviour
auto-patch (default)	Automatically installs patch updates. Minor and major require confirmation.
auto-minor	Automatically installs patch and minor updates. Major requires confirmation.
manual	All updates require explicit user confirmation.
pin	Never update. The user stays on the installed version.

Users configure this per agent in their Selu settings.

Version constraints in agent.yaml

When your agent references a remote capability by image, pin the version:

agent.yaml

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

Supported constraint syntax:

Syntax	Meaning
1.2.3	Exact version
^1.2.0	Compatible with 1.x.x (>= 1.2.0, < 2.0.0)
~1.2.0	Patch-level changes only (>= 1.2.0, < 1.3.0)
>=1.0.0	Any version at or above 1.0.0

Pre-release versions

For testing before a stable release, use pre-release tags:

version: 2.0.0-beta.1

Pre-release versions are never auto-installed. Users must opt in explicitly. They appear in the marketplace with a beta badge.

Note

The marketplace only shows the latest stable version by default. Pre-release versions are visible in the version history dropdown.

Changelogs

While not strictly required, adding a CHANGELOG.md to your agent repository is strongly recommended. The marketplace will display it alongside version history if present.

Follow Keep a Changelog format:

CHANGELOG.md

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

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

Next steps

• Release Pipeline — Automate version bumps and publishing.
• Marketplace Guidelines — Submission requirements.