From ef135696594aea0e8df2310608df325cd197a149 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:43:58 +0000 Subject: [PATCH 1/2] docs: document deprecating a plugin in a datumctl catalog --- datumctl/plugins/publishing-catalogs.mdx | 27 +++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/datumctl/plugins/publishing-catalogs.mdx b/datumctl/plugins/publishing-catalogs.mdx index 8994f7f..2e5b2a1 100644 --- a/datumctl/plugins/publishing-catalogs.mdx +++ b/datumctl/plugins/publishing-catalogs.mdx @@ -75,6 +75,7 @@ A manifest with no header still parses — the only required content is the plug | `spec.description` | Optional | Longer text shown when inspecting the plugin. | | `spec.homepage` | Optional | The plugin's homepage. | | `spec.platforms` | Yes | One entry per supported OS/arch. | +| `spec.deprecated` | Optional | Marks the plugin as deprecated and names its replacement. See [Deprecating a plugin](#deprecating-a-plugin). | **Each entry under `spec.platforms`:** @@ -93,7 +94,7 @@ The binary inside each archive should be named `datumctl-` (or `datumctl-< ## Validating before you publish -Lint a manifest before you ship it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, missing checksums, and invalid platform selectors: +Lint a manifest before you ship it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, missing checksums, invalid platform selectors, and `deprecated` blocks that have no `message` or no `replacement.catalog`: ```bash # Validate a local manifest @@ -132,6 +133,30 @@ Enterprises can constrain which catalogs their users may add through an allow-li See [Adding catalogs](/datumctl/plugins/adding-catalogs#enterprise-guardrails) for how allow-list entries are matched. +## Deprecating a plugin + +When a plugin moves to another catalog, removing its entry right away breaks `datumctl plugin upgrade` for everyone who installed it from your catalog. Instead, keep the entry and mark it deprecated with a message and the plugin that replaces it: + +```yaml +spec: + # ...version, platforms, and other fields as before + deprecated: + message: deploy moved to the ACME Platform catalog. + replacement: + catalog: acme-platform/datumctl-plugins # a catalog source, as `plugin index add` takes + name: deploy # optional; defaults to this plugin's name +``` + +| Field | Required | Purpose | +|-------|----------|---------| +| `deprecated.message` | Yes | Explains why the plugin is deprecated or where it went. | +| `deprecated.replacement.catalog` | Yes | The catalog source of the replacement plugin. | +| `deprecated.replacement.name` | Optional | The replacement plugin's name. Defaults to the deprecated plugin's name. | + +`replacement.catalog` is a catalog source, not a catalog name, because each user picks their own name when they add a catalog. datumctl recognizes the replacement's catalog by comparing sources. For GitHub sources, it matches by owner and repository regardless of case or branch, so `acme-platform/datumctl-plugins`, `github.com/acme-platform/datumctl-plugins`, and `https://raw.githubusercontent.com/acme-platform/datumctl-plugins/main/index.yaml` all name the same catalog. + +A deprecated entry stays installable and upgradable until you remove it from your catalog. Keep publishing releases to it during the deprecation period. datumctl releases without deprecation support ignore the `deprecated` block and keep installing and upgrading the plugin as usual. + ## Versioning guidance `spec.version` is the version datumctl installs when a user runs `datumctl plugin install ` without pinning. Users can pin a specific version with `datumctl plugin install @`. From e40a155b96fddd835692caa632b903141e85a43a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:57:14 +0000 Subject: [PATCH 2/2] docs: describe the deprecated plugin warning on install and upgrade --- datumctl/plugins/publishing-catalogs.mdx | 2 ++ datumctl/plugins/using-plugins.mdx | 15 +++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/datumctl/plugins/publishing-catalogs.mdx b/datumctl/plugins/publishing-catalogs.mdx index 2e5b2a1..cb3f7c0 100644 --- a/datumctl/plugins/publishing-catalogs.mdx +++ b/datumctl/plugins/publishing-catalogs.mdx @@ -155,6 +155,8 @@ spec: `replacement.catalog` is a catalog source, not a catalog name, because each user picks their own name when they add a catalog. datumctl recognizes the replacement's catalog by comparing sources. For GitHub sources, it matches by owner and repository regardless of case or branch, so `acme-platform/datumctl-plugins`, `github.com/acme-platform/datumctl-plugins`, and `https://raw.githubusercontent.com/acme-platform/datumctl-plugins/main/index.yaml` all name the same catalog. +Users who install, restore, or upgrade a deprecated plugin see a warning that names the replacement and the commands to switch to it. See [Deprecated plugins](/datumctl/plugins/using-plugins#deprecated-plugins). + A deprecated entry stays installable and upgradable until you remove it from your catalog. Keep publishing releases to it during the deprecation period. datumctl releases without deprecation support ignore the `deprecated` block and keep installing and upgrading the plugin as usual. ## Versioning guidance diff --git a/datumctl/plugins/using-plugins.mdx b/datumctl/plugins/using-plugins.mdx index 9401c6e..7b41852 100644 --- a/datumctl/plugins/using-plugins.mdx +++ b/datumctl/plugins/using-plugins.mdx @@ -154,6 +154,21 @@ To upgrade every plugin you have installed at once, run `datumctl plugin upgrade `plugin upgrade` runs the same verified install flow as a fresh install. +### Deprecated plugins + +When a catalog marks a plugin as deprecated, usually because it moved to another catalog, datumctl prints a warning when you install, restore, or upgrade that plugin. `plugin upgrade` prints it whether or not a newer version was installed. The install or upgrade still completes. The warning names the replacement and the commands to switch to it: + +```text +warning: deploy is deprecated: deploy moved to the ACME Platform catalog. + To switch to the replacement: + datumctl plugin index add acme-platform acme-platform/datumctl-plugins + datumctl plugin install acme-platform/deploy +``` + +If you already added the replacement's catalog, the warning shows only the `datumctl plugin install` line, using the name you gave that catalog. If your organization's policy disables that catalog, the warning says so instead of suggesting commands. + +Run the suggested commands to switch. After `datumctl plugin install /`, datumctl records the plugin as installed from the new catalog, so `plugin upgrade` uses that catalog and the warning stops. Plugins installed directly from a GitHub release never show this warning. + ## How plugins stay trustworthy datumctl treats a plugin as untrusted code and protects you in a few ways: