Adonia is currently prerelease software. Until a stable 1.0.0 is published, read each release’s changeset and migration notes; prerelease versions may contain intentional breaking cleanup. This page states the policy and current procedure, not evidence that a public 1.0 release has occurred.
Stable ecosystem ABI
From 1.0, three surfaces are semver-major-stable:
- descriptor protocol v1;
ComponentRegistry, including plugin composition and unknown-component behavior;- the server
AdoniaPlugincontract and protocol-v1 hook set.
The wire protocolVersion remains literal 1 through 1.0. Additive changes can keep v1. A post-freeze change to any of these surfaces requires an RFC and a protocol-version impact statement; a breaking change requires the appropriate major/protocol transition.
All other public exports follow normal semver. The generated API reference is the canonical inventory of package/subpath symbols. Anything reachable through a publishable package exports map is public, including type-only exports.
Coupled packages and plugins
Upgrade the Adonia framework packages together. Server and client halves of a plugin must use the same plugin package version. A named UI plugin declares protocolVersion; the registry rejects mismatches and duplicate installation instead of partially registering components. Server plugin descriptor cache identity includes its name, version, and optional configuration cacheKey.
Upgrade procedure
-
Read the release notes and changesets for every version crossed.
-
Upgrade the selected packages with the application’s package manager.
-
Re-run the idempotent configure hook:
node ace configure @adonia/core -
Review generated-file changes rather than overwriting ejected/custom files.
-
Run database migrations and regenerate application manifests through the normal AdonisJS assembler/codegen lifecycle.
-
Run
node ace adonia:doctorand fix failures. -
Typecheck and run the application’s authorization, tenant/parent isolation, CRUD/action, browser accessibility, and deployment smoke suites.
-
Deploy workers before or with web code when action/import/export payloads change.
Back up data before migrations and use the application’s normal rollback strategy. Do not roll back web code while leaving an incompatible worker or migration active.
Deprecations and codemods
Stable removals or incompatible renames require a major release. When a supported migration is mechanical, the release may ship an explicit codemod and document its exact input/output. No general 0.x → 1.0 codemod is promised here: one should exist only for a real breaking migration found by the API review. Never run an unrelated codemod merely to satisfy a checklist.
Generated field/API pages are not hand-edited compatibility shims. Source TSDoc, export maps, generators, and canonical membership checks move together so stale references fail docs:check.
Plugin author responsibilities
Declare supported Adonia and peer ranges, publish server/client halves together, vendor-prefix descriptor keys, test protocol mismatch and missing-half behavior, and record descriptor-affecting configuration in cacheKey. Follow Plugin authoring and link users to package-specific migration notes.