Plugin versioning

Every change to a plugin requires a version bump in metadata.json. This applies to all changes and includes documentation updates, icon replacements, and metadata-only tweaks.

Any PR that modifies plugin files without a version bump is considered incomplete.

Format

Plugin versions follow Semantic Versioning: MAJOR.MINOR.PATCH (e.g. 1.2.3).

{
  "name": "myplugin",
  "version": "1.2.0",
  ...
}

Version bumping

Rules

• The version can never decrease; it must always increase with each change.
• Breaking changes (deleting a data stream, significantly changing its UI parameters) require a major version bump, because existing tiles referencing the old data stream may stop working.

Handle breaking changes gracefully

Rather than immediately deleting a data stream, prefer a two-step approach:

1. Mark the old data stream as deprecated by setting "visibility": "deprecated" and adding a migration hint to the description field (e.g. "Deprecated — use the devicesV2 data stream instead")
2. In a follow-up release, remove the deprecated stream and bump the major version

This gives users time to migrate before the breaking change lands.

Plugin folder versioning

The plugin folder in the repository is also versioned. The folder name (v1, v2) corresponds to the major version in metadata.json. When a breaking change increments the major version, create a new versioned folder rather than overwriting the existing one. This allows users still on the old version to continue using it without disruption.

plugins/
  MyPlugin/
    v1/          ← folder for major version 1
      metadata.json
      ...
    v2/          ← new folder when breaking changes are made
      metadata.json
      ...

Was this article helpful?