dsh-plugin-guide: release engineering for a portfolio of DSH plugins

[PerryLink]

What it is. dsh-plugin-guide is an installable bundle plugin and a knowledge base for building DSH plugins: an archive of the official docs, a Cordis primer, a five-language quick reference, an agent skill, and a small CLI (dsh-plugin-dev) that scaffolds and verifies plugin repositories.

What is new. A chapter the official docs do not cover: maintaining a portfolio of plugins rather than one.

• Version-line matrix: devDependencies pin the newest published line so typecheck fails before your users do; peerDependencies admit both the rc and the alpha windows of @deepseek-ai/*, instead of narrowing to whichever line you happened to develop on.
• Release pipeline: tag-triggered publish with --provenance, and the failure modes that cost real cycles - a release commit missing its lockfile, a token rotated in one repository but not the other thirty, and registry replication delay making a verification job resolve the previous version.
• One version, three surfaces: npm, GitHub Release, mirror. All three verified before a release is called done.
• README parity treated as a build gate rather than documentation etiquette.
• Migration waves for compatibility-breaking releases: detect with a typecheck matrix against the newest line, separate pin updates from semantic redesigns, then execute as one atomic batch with a rollback note per repository.
• A short list of registry behaviours that look like your bug but are not: empty versions[].readme, the roughly 255 character description truncation, and scoped-package download endpoints that return placeholders.

Links.

• Repository: https://github.com/PerryLink/dsh-plugin-guide
• Chapter, English: https://github.com/PerryLink/dsh-plugin-guide/blob/main/guide/release-engineering.md
• Chapter, Chinese: https://github.com/PerryLink/dsh-plugin-guide/blob/main/guide/release-engineering.zh-CN.md

Feedback and corrections welcome, especially from anyone maintaining more than a handful of plugins - the interesting failure modes only appear at that size.