← ClaudeAtlas

dsh-create-upgrade-guidelisted

Use when a deepseek-harness change breaks an externally perceptible surface (CLI, profiles, cordis.yml or settings keys, persisted user data, SDK or wire APIs, published package entry points), or when changing a surface that an unreleased upgrade guide already covers, to write or update docs/upgrade-guide/v<version>/<item>/guide.md.
SOYL-AI/soyl-skills-hub · ★ 0 · Web & Frontend · score 72
Install: claude install-skill SOYL-AI/soyl-skills-hub
# DSH Create Upgrade Guide An upgrade guide tells a reader who runs release vT what to change to run the next release. Write it in the change that introduces the break, as soon as the break is recognized; do not defer it to release preparation. ## Scope Write a guide only for breaks that someone outside the repository can observe after upgrading: - `dsh` commands, flags, and profile names; - `cordis.yml`, patch, overlay, and settings keys or their accepted values; - persisted user data: Session logs, SQLite stores, and user data directories; - TypeScript and Python SDK exports, JSON-RPC, HTTP, and ACP messages; - published package names and entry points. Pre-stable internal APIs whose consumers are all updated in the same change need no guide. A Session-format change still follows [type acknowledgements](../../../docs/cookbook/reviewing-persistence-type-changes.md); its guide states only the reader's actions and links that record. ## Location `docs/upgrade-guide/v<version>/<item>/guide.md` - `<version>` is the `version` field of the root `package.json` when you write the guide, for example `v0.1.7-rc.2`. The guide describes the upgrade from that release to the next one. - `<item>` is a kebab-case name of the changed surface, for example `profile-flag-rename`. - Each item directory holds exactly `guide.md`, its Chinese counterpart `guide.zh.md`, and the pairing record `guide.i18n.yaml`: no index, no attachments. ## Maintenance While the root version is unchanged, the