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; its guide states only the reader's actions and links that record.

Location

docs/upgrade-guide/v<version>/<item>/guide.md