diff --git a/datumctl/plugins/publishing-catalogs.mdx b/datumctl/plugins/publishing-catalogs.mdx index 8994f7f..cb3f7c0 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,32 @@ 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. + +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 `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 @`. diff --git a/datumctl/plugins/using-plugins.mdx b/datumctl/plugins/using-plugins.mdx index 9401c6e..a15ce41 100644 --- a/datumctl/plugins/using-plugins.mdx +++ b/datumctl/plugins/using-plugins.mdx @@ -85,7 +85,7 @@ datumctl plugin install your-org/datumctl-example@v1.2.0 Without a version, datumctl installs the release GitHub marks as latest. If the repository has published only pre-releases, datumctl installs the highest pre-release instead, and `datumctl plugin upgrade` follows newer pre-releases the same way. - If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose. + If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose. A deprecated plugin and its same-named replacement don't count as a collision; see [Deprecated plugins](#deprecated-plugins). ### Pinning a version @@ -154,6 +154,31 @@ 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. + +After you add the replacement's catalog, a bare-name install such as `datumctl plugin install ipam` installs the replacement when it has the same name. datumctl doesn't report that the name exists in multiple catalogs. It first prints this note to stderr, once for each deprecated match it skips: + +```text +note: in is deprecated; installing its replacement from +``` + +If other catalogs also have a plugin with that name, the collision error lists only those catalogs and the replacement. A replacement with a different name isn't picked this way. Install it with `datumctl plugin install /`. + +`datumctl plugin install --all-available` skips a deprecated plugin you haven't installed and prints `Skipped : deprecated`. A deprecated plugin you already have is still upgraded, or reported as up to date, and datumctl prints its deprecation warning. + ## How plugins stay trustworthy datumctl treats a plugin as untrusted code and protects you in a few ways: