Extension Version Lifecycle

Extensions ship on their own cadence, but installations are pinned to a specific version to keep workflows predictable. This guide explains how semantic versioning, upgrades, and deprecations work inside Kiket.

Semantic versioning

Extensions must use MAJOR.MINOR.PATCH:

Change	Example	Notes
Bug fix / refactor	1.4.1 → 1.4.2	No schema or API changes.
Backwards-compatible feature	1.4.2 → 1.5.0	New optional hooks/config fields allowed.
Breaking change	1.x.x → 2.0.0	Requires admin attention; may need new secrets or migrations.

Manifests include a compatibility block so Marketplace knows which platform version is required and which legacy versions are deprecated:

compatibility:
  kiket: ">=1.42.0"
  deprecates:
    - version: "<1.5.0"
      deadline: "2026-01-31"
      notice: "Rotate CRM secrets before upgrading."

Installations & upgrades

1. Pinning – When you install a product blueprint, each extension instance records current_version. Marketplace never auto-upgrades without approval.
2. Notifications – When a maintainer publishes a new version, admins see changelog highlights plus required actions (new secrets, migrations, downtime considerations).
3. Validation – Before upgrading, Kiket verifies manifest schema, dependency compatibility, and Secret Store readiness. Blocking items are surfaced inline.
4. Execution – Upgrades clone the new repo/tag, replay configuration loaders, and re-run extension setup jobs. If anything fails, we roll back to the previous version automatically.
5. Rollback – Admins can roll back within 30 days via UI or kiket marketplace upgrade --rollback. Metadata retains previous_version for auditing.

Deprecations

Maintainers register deprecations through the registry API. Kiket then:

• Shows warning banners 30 days before the deadline.
• Blocks new installs of deprecated versions.
• Requires admins to acknowledge risk if they choose to defer beyond the deadline.
• Automatically schedules reminders (email + in-app) for affected organizations.

Lifecycle states

State	Description	Marketplace behavior
Active	Fully supported release.	Install/upgrade target.
Maintenance	Security & bug fixes only.	Install allowed, badge shown.
Deprecated	Replacement available.	New installs blocked; upgrades prompted.
Retired	No longer supported.	Removed from listings; invocations blocked unless waiver.

SDK awareness

Both the TypeScript and Python SDKs expose context.extension.version, letting you branch logic when supporting multiple versions at once. Use that rather than parsing manifests at runtime.

Release checklist

1. Bump the version in manifest.yaml.
2. Update CHANGELOG.md and note breaking changes.
3. Add/adjust compatibility entries.
4. Run regression tests + upgrade scripts against the minimum supported Kiket version.
5. Publish to the registry (or push the marketplace bundle) and announce via the developer portal.

Following this policy keeps upgrades predictable and gives downstream teams enough time to react when you need to introduce breaking changes.