Safe DSH upgrade: compatibility gate, backup, and release check

1. Record the working baseline

Before downloading a new host, capture the current DSH and Node versions, every profile you use, exact plugin versions, lockfiles, and one deterministic smoke test per important capability. A rollback is impossible if the previous state is only remembered approximately.

node -v
dsh --version
dsh --profile web --dump-config

2. Read the release diff

Compare the currently installed release with the target, then check open failure intelligence created after that target shipped. Release notes describe intended changes; dated reproductions reveal environment-specific faults that may not yet have an official advisory.

• Confirm GitHub Releases and npm latest name the same target version.
• Read the official notes and the registry breaking-change page.
• Search by exact error string, not only by plugin name.
• Do not infer that no release-note warning means no migration risk.

3. Gate every required plugin

A useful compatibility cell must match the selected package artifact, target DSH version, Node runtime, profile or execution surface, and freshness window. Anything else is information, but not permission to upgrade the working profile.

4. Create a restorable backup

Back up the complete DSH home using a tool that preserves file contents, metadata, profile manifests, lockfiles, and storage databases. Store the backup outside the directory being upgraded and verify that it can be listed or opened before continuing.

5. Rehearse in a disposable profile

Install the target DSH and the exact gated plugin artifacts into an isolated profile or DSH home. Run profile composition first, then boot, then one low-risk capability smoke test. Test Web, Headless, and TUI separately when you use more than one surface.

• Verify package installation and profile registration as separate facts.
• Require the profile to compose before running a capability test.
• Preserve the exact failure reason instead of reducing it to a red badge.
• Do not reuse a historical pass after either the plugin or host changes.

6. Upgrade the working profile only after rollback passes

Schedule the change when interruption is acceptable. Keep the prior DSH package reference, plugin artifacts, backup location, and deterministic control beside the upgrade notes. After upgrading, repeat the same compose, boot, and capability tests before resuming normal work.

About dsh-compat-guard

The community dsh-compat-guard project proposes preflight checks, a per-profile lockfile, automatic DSH-home backups, snapshots, and rollback. Its public discussion reports early matrix results, but storage-format fingerprints are explicitly described as incomplete. Review the source and current evidence before relying on it.