From 6a27219b48b3b1479bffb9c8350d13af54e716e5 Mon Sep 17 00:00:00 2001 From: Michael Costello Date: Tue, 17 Nov 2026 14:20:09 -0500 Subject: [PATCH] docs: Explain plugin deprecation in help and docs Catalog authors need to know how to deprecate a plugin, and users need to know what the warning means and how to switch. The --help text for plugin install, upgrade, list, search, browse, and index validate now describes the deprecation warning, the deprecated list status, the search tag and JSON field, bare-name preference for a replacement, --all-available skipping deprecated plugins, and the new validation checks. Each says the replacement commands appear only when the catalog names a replacement. The plugin system design doc also covers the notice for a replacement whose catalog an allow-list disables. Resolves: #372 Resolves: #355 Co-Authored-By: Claude Opus 5.5 --- docs/developer/plugins.md | 6 ++++-- internal/cmd/plugin/browse.go | 3 ++- internal/cmd/plugin/index.go | 3 ++- internal/cmd/plugin/install.go | 7 ++++++- internal/cmd/plugin/list.go | 3 ++- internal/cmd/plugin/search.go | 4 +++- internal/cmd/plugin/upgrade.go | 4 +++- 7 files changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/developer/plugins.md b/docs/developer/plugins.md index a7cb15c..a832552 100644 --- a/docs/developer/plugins.md +++ b/docs/developer/plugins.md @@ -181,8 +181,10 @@ warning: ipam is deprecated: ipam moved to the Milo catalog. ``` If the replacement's catalog is already registered, the notice shows only the -`plugin install` line. Installs and upgrades still proceed. Plugins installed -directly from GitHub have no catalog entry and get no notice. +`plugin install` line. When an allow-list disables that catalog, the notice +says the catalog is disabled and prints no commands. Installs and upgrades +still proceed. Plugins installed directly from GitHub have no catalog entry and +get no notice. When both a deprecated plugin and a replacement with the same name are available, a bare-name install such as `datumctl plugin install ipam` picks the diff --git a/internal/cmd/plugin/browse.go b/internal/cmd/plugin/browse.go index b3e79bb..17ccd72 100644 --- a/internal/cmd/plugin/browse.go +++ b/internal/cmd/plugin/browse.go @@ -34,7 +34,8 @@ func browseCmd() *cobra.Command { Type to filter, inspect a plugin's description, version, source catalog, and trust badge ("official" for Datum's curated datum catalog, "third-party" for catalogs you added), and install the selected plugin in place. Use --index to - scope the browser to a single catalog.`), + scope the browser to a single catalog. Deprecated plugins are tagged + "(deprecated)", and their details show the deprecation warning.`), Example: templates.Examples(` # Browse all catalogs datumctl plugin browse diff --git a/internal/cmd/plugin/index.go b/internal/cmd/plugin/index.go index 2d631c3..ca0992b 100644 --- a/internal/cmd/plugin/index.go +++ b/internal/cmd/plugin/index.go @@ -388,7 +388,8 @@ func indexValidateCmd() *cobra.Command { Long: templates.LongDesc(` Lint a catalog manifest before you publish it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, - missing checksums, and invalid platform selectors. + missing checksums, invalid platform selectors, and an incomplete + deprecated block (no message or no replacement.catalog). The source may be a local path, an HTTPS URL, or a GitHub owner/repo.`), Example: templates.Examples(` diff --git a/internal/cmd/plugin/install.go b/internal/cmd/plugin/install.go index c4bd4b9..60d62da 100644 --- a/internal/cmd/plugin/install.go +++ b/internal/cmd/plugin/install.go @@ -31,6 +31,10 @@ func installCmd(_ *client.DatumCloudFactory) *cobra.Command { With no arguments, restores all previously installed plugins to their recorded versions. Use this to reproduce a plugin set on a new machine. +Installing or restoring a deprecated plugin prints a deprecation warning and, +when the catalog names a replacement, how to switch to it. A bare name prefers +a deprecated plugin's replacement when both are available. + With a plugin name argument, installs from a registered catalog: - name resolves against the official datum catalog first, then any other registered catalog; a name found in more than @@ -49,7 +53,8 @@ alone. A plugin of the same name installed from another catalog or from GitHub is skipped, not replaced. One failed plugin does not stop the others; failures are listed at the end and the command exits non-zero. A third-party catalog asks for confirmation first, listing the plugins it would install; pass --yes -to confirm without the prompt. +to confirm without the prompt. Deprecated plugins that are not installed are +skipped. The plugin binary is written to the managed plugins directory (~/.datumctl/plugins/ by default).`, diff --git a/internal/cmd/plugin/list.go b/internal/cmd/plugin/list.go index b223d7c..02b9c6c 100644 --- a/internal/cmd/plugin/list.go +++ b/internal/cmd/plugin/list.go @@ -24,7 +24,8 @@ func listCmd() *cobra.Command { Status column indicators: ok Plugin is installed and compatible with this datumctl. update A newer version is available in its catalog. - deprecated Its catalog marks the plugin deprecated. + deprecated Its catalog marks the plugin deprecated. A warning is printed + after the table for every deprecated plugin, even if shown as ! or ?. ! Built for a different datumctl version. ? Version info unavailable. diff --git a/internal/cmd/plugin/search.go b/internal/cmd/plugin/search.go index 1900072..7aa0de6 100644 --- a/internal/cmd/plugin/search.go +++ b/internal/cmd/plugin/search.go @@ -51,7 +51,9 @@ func searchCmd() *cobra.Command { Run 'datumctl plugin install ' to install a plugin listed here. Use -o json for machine-readable output, or -o name for one plugin name - per line.`), + per line. Deprecated plugins are tagged [deprecated]; table output prints a + warning with the replacement after the table, and -o json adds a + "deprecated" field to them.`), Example: templates.Examples(` # List all available plugins across catalogs datumctl plugin search diff --git a/internal/cmd/plugin/upgrade.go b/internal/cmd/plugin/upgrade.go index 1f955ca..c314652 100644 --- a/internal/cmd/plugin/upgrade.go +++ b/internal/cmd/plugin/upgrade.go @@ -29,7 +29,9 @@ func upgradeCmd(_ *client.DatumCloudFactory) *cobra.Command { originally installed from, using the same flow as 'datumctl plugin install': SHA256 verification, manifest check, and compatibility validation. A plugin that is already at its latest version is left - untouched. + untouched. A deprecated plugin still upgrades; the command prints a + deprecation warning and, when the catalog names a replacement, how to + switch to it. With --all, a plugin that fails to upgrade does not stop the others; the failures are listed together once every plugin has been attempted.`),