Skip to content

docs: Explain plugin deprecation in help and docs - #379

Merged
0xmc merged 2 commits into
mainfrom
feat/372-deprecation-help
Nov 18, 2026
Merged

0xmc merged 2 commits into
mainfrom
feat/372-deprecation-help

Conversation

@0xmc

@0xmc 0xmc commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Catalog authors need to know how to deprecate a plugin, and users need to know what the deprecation warning means and how to switch.

The help for the plugin commands now describes the warning, the deprecated status and search tag, and the new catalog validation checks. The design doc adds the notice for a replacement catalog an allow-list disables.

This is the last PR in the stack, so merging it completes #355.

Test plan

  • Each command's help names only flags, statuses, and output that exist, and mentions replacement commands only when the catalog names one
  • On a build of the whole stack, a user finds a deprecated plugin, adds the replacement's catalog, moves to it, and upgrades with no further warning
  • Build, vet, and the plugin tests pass

Stacked on #378. Fixes #372
Fixes #355

🤖 Generated with Claude Code

@0xmc
0xmc force-pushed the feat/372-deprecation-help branch from c9a6667 to 84bde3b Compare November 17, 2026 19:21
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 <noreply@anthropic.com>
@0xmc
0xmc force-pushed the feat/372-deprecation-help branch from 84bde3b to 6a27219 Compare November 17, 2026 19:21
@0xmc
0xmc marked this pull request as ready for review November 18, 2026 17:08
@0xmc
0xmc requested a review from a team as a code owner November 18, 2026 17:08
ecv
ecv previously approved these changes Nov 18, 2026

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve.

Each new help line matches the code at 6a27219: browse appends " (deprecated)", search prefixes "[deprecated] " and adds a deprecated JSON field, validate reports a deprecated block with no replacement.catalog, --all-available skips deprecated plugins that are not installed, and the disabled-catalog notice prints the reason and no commands. It sits on #378, which is still open, so it merges after that one.

Base automatically changed from feat/371-deprecation-listings to main November 18, 2026 17:17
@0xmc
0xmc dismissed ecv’s stale review November 18, 2026 17:17

The base branch was changed.

@0xmc
0xmc enabled auto-merge November 18, 2026 17:26
@0xmc

0xmc commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Both reviewers agreed on this PR, and CI is green on the current head.

pr-adversary: VERDICT merge. It ran gh pr view; git diff fcf0088...c9a6667; grep -i deprecat over internal/cmd/plugin; reads of deprecation.go, install_all_available.go, install.go and search.go; grep pluginstore; go build, vet and test; gh pr checks 379. Every help and doc claim it checked matches the code: the install, restore and upgrade warnings, the --all-available skip, the list and search statuses and notices, the search -o json field and table-only notices, the disabled-catalog notice with no commands, and the validator checks.

pr-conventions-reviewer: VERDICT merge. It ran gh pr view; git diff and git log fcf0088..c9a6667; gh pr list for overlap; a grep of commit-conventions; git log fcf0088.

Both reviewers raised only nits, and I applied them before this pass: the ragged docs paragraph was reflowed and the browse help now mentions deprecation. Both went into the single feature commit (c9a6667 amended to 6a27219). The "Fixes #355" concern is resolved because the PR now targets main. The head, c1f8932, adds only the merge of main from GitHub's Update branch.

CI: ci / Build and test passed on c1f8932, and license/cla passed.

This is the last PR of the stack. Merging it closes #372 and #355.

Auto-merge is enabled with the merge method. The ruleset requires one approving review, a code owner review, and approval of the last push, so the PR waits for a human approval.

@0xmc
0xmc requested a review from ecv November 18, 2026 17:26

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve.

c1f8932 only merges main now that the rest of the stack has landed, plus three datum-cloud/actions bumps; the help and doc text is unchanged from 6a27219, which I approved.

@0xmc
0xmc merged commit 7a7db17 into main Nov 18, 2026
2 checks passed
@0xmc
0xmc deleted the feat/372-deprecation-help branch November 18, 2026 18:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document plugin deprecation for catalog authors Support deprecating a catalog plugin in favor of another

2 participants