From 07b1cfc2d28e3b248b7888b9e678c994df601e07 Mon Sep 17 00:00:00 2001 From: Lance Pioch Date: Tue, 8 Sep 2026 20:21:18 -0400 Subject: [PATCH 1/2] Document the plugin api contract and Docker panel updates Adds the api_version field and compatibility policy to the plugins page, updates the panel_version caret to its new composer range semantics, and adds a Docker tab plus checksum verification steps to the panel update guide. --- docs/panel/advanced/plugins.mdx | 23 ++++++++++++++++++++++- docs/panel/update.mdx | 18 ++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/panel/advanced/plugins.mdx b/docs/panel/advanced/plugins.mdx index 3dc4eeb..7e70047 100644 --- a/docs/panel/advanced/plugins.mdx +++ b/docs/panel/advanced/plugins.mdx @@ -99,6 +99,7 @@ Most of the fields inside the `plugin.json` are generated when running the [arti | class | Yes | The name of the plugin main class. | | panels | No | Array of [FilamentPHP panel](#filament-panels) ids the plugin should be loaded on. When not set the plugin will be loaded on all panels. | | panel_version | No | The panel version required for the plugin. See [below](#panel-version) for more information. | +| api_version | No | The plugin api version the plugin targets. When not set, version 1 is assumed. See [below](#api-version) for more information. | | composer_packages | No | Array of additional composer packages. Key is the package name and value is the version. See [below](#additional-composer-dependencies) for more information. | @@ -171,7 +172,13 @@ Example: In your `plugin.json` you can specify a `panel_version` that is used for compatibility checks. When not set, the plugin will be loaded regardless of the panel version. -You can add a `^` in front of the version to make it a minimum constraint instead of a strict one, e.g. `1.2.0` means "_only_ version 1.2.0" while `^1.2.0` means "version 1.2.0 _or higher_". +You can add a `^` in front of the version to turn the strict constraint into a range with the same semantics as composer's caret, e.g. `1.2.0` means "_only_ version 1.2.0" while `^1.2.0` means "version 1.2.0 or higher, but below 2.0.0". For `0.x` constraints the range caps at the next minor instead, e.g. `^0.3` allows 0.3.0 up to (but not including) 0.4.0. + +#### Api version + +In your `plugin.json` you can specify an `api_version` that declares which version of the plugin api your plugin targets. The current plugin api version is **1**. + +When not set, version 1 is assumed and the plugin list shows a small warning under the plugin status. If a plugin declares a newer api version than the panel supports, the panel refuses to load it and marks it as incompatible. This way a future breaking change to the plugin api can't take down a panel that still runs older plugins. ### Filament Resources @@ -381,6 +388,20 @@ public function register(): void } ``` +## Compatibility Policy + +The plugin api follows the panel's [semantic versioning](https://semver.org/). The stable surface plugins can rely on consists of: + +- The `plugin.json` schema documented on this page +- The `HasPluginSettings` interface +- Automatic discovery and registration of service providers, artisan commands, migrations, views, translations and seeders as described above +- The `panel_version` compatibility semantics (strict and `^` range constraints) +- The handling of `composer_packages` + +Breaking changes to this surface only happen with a new panel major version, and deprecations are announced at least one minor version ahead. The `api_version` field exists so the panel can detect plugins that target a newer, incompatible plugin api. + +Anything not listed above, in particular the panel's internal services, models, and Filament internals, can change in any release. The static registration hooks documented on this page (custom permissions, resource modification, etc.) are kept working on a best-effort basis. + ## Publish a Plugin diff --git a/docs/panel/update.mdx b/docs/panel/update.mdx index f86b764..28ad947 100644 --- a/docs/panel/update.mdx +++ b/docs/panel/update.mdx @@ -21,6 +21,16 @@ Please see the chart below for how these versions line up. You have two options for updating: use the automatic update script (recommended) or do the update steps manually. + + A [Docker install](./advanced/docker) updates by pulling the new image. From the directory containing your `compose.yml`, run: + + ```sh + docker compose pull + docker compose up -d + ``` + + Database migrations run automatically when the new container starts. + Simply run the command below and the update script will guide you through the process: @@ -49,6 +59,14 @@ You have two options for updating: use the automatic update script (recommended) curl -L https://github.com/pelican/panel/releases/latest/download/panel.tar.gz | sudo tar -xzv ``` + To verify the archive before extracting it, download it together with its `checksum.txt` release asset instead: + + ```sh + curl -LO https://github.com/pelican/panel/releases/latest/download/panel.tar.gz + curl -LO https://github.com/pelican/panel/releases/latest/download/checksum.txt + sha256sum -c checksum.txt && sudo tar -xzvf panel.tar.gz && rm panel.tar.gz checksum.txt + ``` + Once the archive is downloaded and extracted we need to set the correct permissions on the cache and storage directories to avoid any webserver related errors. From 78f225d615f1e741e92827f9abe4337016cdd44b Mon Sep 17 00:00:00 2001 From: Lance Pioch Date: Tue, 8 Sep 2026 20:35:42 -0400 Subject: [PATCH 2/2] Document the 0.0.x caret cap --- docs/panel/advanced/plugins.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/panel/advanced/plugins.mdx b/docs/panel/advanced/plugins.mdx index 7e70047..0db63bf 100644 --- a/docs/panel/advanced/plugins.mdx +++ b/docs/panel/advanced/plugins.mdx @@ -172,7 +172,7 @@ Example: In your `plugin.json` you can specify a `panel_version` that is used for compatibility checks. When not set, the plugin will be loaded regardless of the panel version. -You can add a `^` in front of the version to turn the strict constraint into a range with the same semantics as composer's caret, e.g. `1.2.0` means "_only_ version 1.2.0" while `^1.2.0` means "version 1.2.0 or higher, but below 2.0.0". For `0.x` constraints the range caps at the next minor instead, e.g. `^0.3` allows 0.3.0 up to (but not including) 0.4.0. +You can add a `^` in front of the version to turn the strict constraint into a range with the same semantics as composer's caret, e.g. `1.2.0` means "_only_ version 1.2.0" while `^1.2.0` means "version 1.2.0 or higher, but below 2.0.0". For `0.x` constraints the range caps at the next minor instead, e.g. `^0.3` allows 0.3.0 up to (but not including) 0.4.0, and `0.0.x` constraints cap at the next patch, e.g. `^0.0.3` only allows 0.0.3. #### Api version