---
title: "Upgrade and compatibility policy"
description: "Plan prerelease upgrades and follow the compatibility guarantees after 1.0."
image: "https://adonia.pages.dev/og.png"
version: "next"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonia.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade and compatibility policy

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:

1. descriptor protocol v1;
2. `ComponentRegistry`, including plugin composition and unknown-component behavior;
3. the server `AdoniaPlugin` contract 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](/reference/api) 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

1. Read the release notes and changesets for every version crossed.
2. Upgrade the selected packages with the application's package manager.
3. Re-run the idempotent configure hook:

```sh
   node ace configure @adonia/core
```

4. Review generated-file changes rather than overwriting ejected/custom files.
5. Run database migrations and regenerate application manifests through the normal AdonisJS assembler/codegen lifecycle.
6. Run `node ace adonia:doctor` and fix failures.
7. Typecheck and run the application's authorization, tenant/parent isolation, CRUD/action, browser accessibility, and deployment smoke suites.
8. 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](/guide/plugin-authoring) and link users to package-specific migration notes.

Source: https://adonia.pages.dev/guide/upgrade-policy/index.mdx