> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/mini-apps-platform/14-breaking-change-policy.md).

# Breaking change policy

Once we ship SDK 1.0.0, the contract enters semver. This document is the public commitment about how breaking changes are handled.

## Definitions

* **Patch (1.0.0 → 1.0.1):** bug fixes; behavior matches docs better. No partner action required.
* **Minor (1.0.0 → 1.1.0):** additive only — new methods, new optional arguments, new permission keywords, new manifest fields. Bundles with `targetSdkVersion: "1.0"` continue to work without modification.
* **Major (1.0.0 → 2.0.0):** anything not covered above — renames, removals, semantic changes. Triggers the deprecation flow below.

## Pre-deprecation announcement

For any candidate breaking change, the platform team publishes:

* a written notice via the partner dashboard and email to all known partners;
* a target deprecation date;
* a migration guide before the announcement is published.

## Deprecation window

After the announcement:

| Phase             | Duration  | What happens                                                                                                                              |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Soak              | 1 quarter | Method continues to work without warnings. Telemetry tracks usage.                                                                        |
| Warn              | 1 quarter | Method works, but emits a host-side warning event partners can see in dashboards. CLI lints flag usage.                                   |
| Remove (in major) | release   | Method either errors with `code: "deprecated_removed"` (carrying a link to the migration page) or is shimmed via the bridge compat layer. |

```mermaid
flowchart LR
    A["Announcement<br/>(notice + migration guide)"]
    S["Soak (1 quarter)<br/>works silently<br/>telemetry only"]
    W["Warn (1 quarter)<br/>works + warns<br/>CLI lint flags it"]
    R["Remove (next major)<br/>errors with<br/>deprecated_removed<br/>or shimmed"]
    A --> S --> W --> R
```

The shim path is preferred when the new behavior can be expressed mechanically from the old call shape; otherwise hard removal is used.

## Compat shims

The bridge maintains a per-major-version shim layer (see [`06-bridge-and-codegen.md`](/docs/integrations/mini-apps-platform/06-bridge-and-codegen.md#compatibility-shims)). Each shim has a documented kill date — typically **the next major version's release**. So a shim added in 2.0 to support 1.x callers is removed when 3.0 ships.

## Manifest schema changes

`based.json` follows the same policy as the API surface. Adding a new manifest field is a minor bump; removing or renaming one is a major bump.

The validator never silently ignores unknown fields, but it warns rather than rejects on **forward-compatible** unknown fields (those introduced in a later minor than the bundle's `targetSdkVersion`).

## What partners can rely on

Once a method or manifest field is documented in a 1.x release:

* **Patch / minor:** stays callable with the same arguments and same semantics until the next major.
* **Major:** at least 2 quarters of advance notice, a migration guide, a shim where mechanically possible.
* **Never:** silent removal, silent rename, silent semantic change.

## What partners cannot rely on

* Stable error `message` strings (they may be tenant-localized or reformatted). Always switch on `code`, never `message`.
* Stable telemetry event names emitted by the host on behalf of mini-apps.
* Stable internal field names in `based.theme.colors` beyond the documented allowlist (`accent`, `accentText`, `chartUp`, `chartDown`).

## Process

Internal change proposals that touch the contract follow this flow:

1. RFC PR against `docs/mini-apps/03-host-contract.md` or `docs/mini-apps/04-manifest.md`. Required reviewers: platform team lead + security reviewer for any signing/nav/permission change.
2. If RFC is breaking → schedule deprecation as above. Include the announcement draft in the RFC.
3. If RFC is additive → land in next minor; update `13-changelog.md` and the docs site reference.
4. Bridge codegen (planned Phase 4.5) regenerates types and shims from the Dart interface; no hand edits to generated files.