Upgrading the SDK

mint-sdk ships independently from the platform on its own tag stream (sdk-v*). Plugins follow at their own pace. This page covers when to upgrade, how to upgrade safely, and how to handle SDK-major breaks.

When to upgrade

Trigger	Action
New SDK feature you need	Bump the floor in your mint-sdk range; release a minor version
SDK security fix	Bump the floor; release a patch
New SDK major (breaking)	Plan a migration; release a major version of your plugin
Routine maintenance	Bump the ceiling when a new SDK minor lands and you've tested

You don't have to upgrade on every SDK release. Pinning to mint-sdk>=1.0.0,<2.0.0 and staying there for the lifetime of SDK 1.x is a perfectly reasonable strategy.

Routine upgrade flow

# In your plugin project
mint sdk update

This:

1. Reads pyproject.toml and bumps the first mint-sdk version in the dependency spec to the latest stable patch by default
2. Reads frontend/package.json and updates @morscherlab/mint-sdk similarly
3. Runs uv sync and bun install to apply the changes
4. Re-renders generated AI-assistant instructions when the project has one of the scaffolded files

After running:

uv run pytest -v
mint doctor
mint dev    # smoke test

Commit the lockfile changes. The next CI run validates the new version against your test suite.

Use mint sdk update --scope minor when you want the newest SDK minor in the same major, or --dry-run to preview. For SDK-major upgrades, edit the full dependency range manually; if your spec has an upper bound such as <2.0.0, a mechanical version replacement is not enough.

Bumping the ceiling for a new SDK major

When mint-sdk 2.0 lands, your >=1.0.0,<2.0.0 range excludes it. To opt in:

1. Read the SDK changelog for breaking changes
2. Update your plugin code to handle the breaks
3. Bump the range to >=2.0.0,<3.0.0
4. Release a major version of your plugin (since the floor is now 2.0)

# pyproject.toml — before
[project]
dependencies = [
  "mint-sdk>=1.0.0,<2.0.0",
]

# pyproject.toml — after
[project]
dependencies = [
  "mint-sdk>=2.0.0,<3.0.0",
]

Release 2.0.0 of your plugin alongside.

Supporting two SDK majors

Some plugins want to keep working under both old and new SDK majors during a transition window. Pattern:

[project]
dependencies = [
  "mint-sdk>=1.5.0,<3.0.0",   # spans two majors
]

In code, branch on SDK version where APIs differ:

import mint_sdk

if mint_sdk.__version__.startswith("2."):
    from mint_sdk import NewAccessor
    accessor = NewAccessor()
else:
    from mint_sdk import OldAccessor
    accessor = OldAccessor()

This trades plugin code complexity for compatibility breadth. Worthwhile only when you have users you can't easily move forward.

Reading the SDK changelog

Each SDK release publishes its changelog at:

• MINT/packages/sdk-python/CHANGELOG.md — Python SDK
• MINT/packages/sdk-frontend/CHANGELOG.md — Frontend SDK

For breaking changes, the changelog entries follow the pattern:

### Removed (BREAKING)
- `OldAccessor.foo()` — replaced by `NewAccessor.foo()` in v2.0. Migration: replace `Old` with `New` and the API is otherwise identical.

Beta SDK testing

When the SDK ships a 2.0.0-beta.1, opt your plugin into the beta channel:

[project]
dependencies = [
  "mint-sdk>=2.0.0b1,<3.0.0",
]

uv sync
uv run pytest -v

mint sdk update only selects stable semver releases, so beta testing starts by editing the dependency range explicitly. Run your full test suite. File any issues against MorscherLab/MINT. Once 2.0 stable lands, drop the b1 from your range.

Don't ship plugin releases against SDK betas

A plugin built against mint-sdk==2.0.0b1 may not work against mint-sdk==2.0.0 if a beta-only API changes. Test against beta, ship against stable.

SDK-major break: a worked example

Suppose mint-sdk 2.0 renames PlatformContext.get_plugin_data_repository() to PlatformContext.plugin_data_repo().

Single-major support

# Before (1.x)
async def initialize(self, context=None):
    self._context = context
    self._data_repo = context.get_plugin_data_repository() if context else None

# After (2.x only)
async def initialize(self, context=None):
    self._context = context
    self._data_repo = context.plugin_data_repo() if context else None

Bump your plugin's major; done.

Two-major support during the transition

async def initialize(self, context=None):
    self._context = context
    if context is None:
        self._data_repo = None
    elif hasattr(context, "plugin_data_repo"):
        self._data_repo = context.plugin_data_repo()         # 2.x
    else:
        self._data_repo = context.get_plugin_data_repository()  # 1.x

Ship as a minor version with the broader range. Drop the 1.x branch when you bump to a major release.

Frontend SDK upgrades

The frontend SDK ships on the same tag stream, with the same major-version cadence. Frontend breaks are usually:

• Component renames or removed components → search-and-replace + storybook visual review
• Composable signature changes → TypeScript catches them at build time
• Token renames → grep for the old variable name in .css and Vue templates

cd frontend
bun update @morscherlab/mint-sdk
bun run type-check   # surfaces breaks immediately
bun run build

For visual review, run your frontend's Histoire (if you have one) or bun run dev and click through the affected pages.

Skipping SDK majors

It's fine to skip an SDK major if its features don't matter to you:

mint-sdk 1.x ──► your plugin 1.x ─┐
mint-sdk 2.x  (skip)              │
mint-sdk 3.x ──► your plugin 2.x ◄┘

Your plugin can jump from mint-sdk>=1.0.0,<2.0.0 directly to >=3.0.0,<4.0.0. Read the cumulative changelogs (1→2 + 2→3) to know what to migrate.

Notes

• The SDK's internal modules (mint_sdk._discover, mint_sdk._version, etc.) are private. Don't import them — they break without notice. Stick to the symbols documented in mint_sdk/__init__.py.
• A plugin pinned to mint-sdk==1.5.3 is fragile. The marketplace registry does not infer compatibility from pyproject.toml, so test the plugin against supported platform releases and set min_platform_version deliberately in the registry entry.
• For long-lived plugins, schedule a quarterly "upgrade SDK" task — the longer you wait, the bigger the diff and the harder the migration.

Related

• Versioning — bumping your plugin's version when the SDK changes
• CI patterns → SDK-compatibility check — automated detection