Versioning
Versioning & updates
Ship changes to a published extension without breaking installs — semantic versions, stable identity, and compatible manifests.
A published extension evolves. Versioning rules keep updates predictable for the workspaces that have installed it.
Identity vs. version
metadata.name — identity (never changes)The stable machine identifier. Changing it creates a different extension, not an update. Keep it constant for the life of the extension.
metadata.version — the release (bumps each change)A semantic version (MAJOR.MINOR.PATCH). Bump it every time you ship.
Semantic versioning
Use semver to signal the nature of a change:
| Bump | When | Examples |
|---|---|---|
PATCH (1.0.0 → 1.0.1) | Backwards-compatible fixes | Bug fix, perf, copy change |
MINOR (1.0.0 → 1.1.0) | Backwards-compatible additions | New entry point, new tool, newly claimed type |
MAJOR (1.0.0 → 2.0.0) | Breaking changes | Removed/renamed scope, removed tool, changed I/O schema |
What counts as breaking
Breaking changes need a MAJOR bump
- Removing or renaming a custom scope other extensions may rely on.
- Removing a tool or changing its
input-schema/output-schemaincompatibly. - Dropping a claimed MIME/file type users depend on.
- Requesting new permissions — these require re-consent by an admin.
Permissions changes require re-consent
If a new version requests additional permissions or defines new scopes, the workspace admin must
consent again before the new version becomes active. Plan permission changes deliberately and explain
them in your release notes — surprise scope requests stall upgrades.
Forward-compatible manifests
Keep api-version: verentis.io/v1 and add fields additively. The manifest schema is designed so new
optional fields don't break older installs; avoid relying on undocumented behaviour.
Registry versions are immutable
Once a version is uploaded to the marketplace registry it can never be replaced — re-publishing
acme/my-app@1.0.0 is rejected. Ship a fix as 1.0.1. If a published version must be withdrawn
(broken build, security issue), yank it: verentis yank my-app 1.0.0 hides it from the catalog and
new installs while keeping the artifact for audit. Yanking doesn't touch existing installs.
Updating an installed extension
Because install is "a manifest node in the VFS", an update is simply a new package version replacing the installed content (via the marketplace, or by updating the file for loose manifests). Resolution, registration and — where permissions changed — consent re-run against the new version. Each new version goes through moderation before it becomes installable.
Treat each release like an API release: stable identity, semantic version, clear notes, and additive changes wherever possible.
You've reached the end
That's the full developer journey — from understanding the platform to publishing an extension. Revisit the app and engine guides as you build, and keep the manifest references close.
Return to the developer home.