Updating a DSH plugin feels safe until it isn't. A new version can change a config key, drop a dependency, or shift a score from B to D overnight. This guide walks through a pre-update check, a snapshot step, a one-at-a-time update, and a concrete rollback — so an upgrade never turns into an outage.
Step 1 — Pre-update check (5 minutes)
Before you touch anything, confirm the plugin is worth updating and that the new version is safe:
- Read the changelog. Look for breaking changes, removed flags, or renamed config keys.
- Compare the score delta. A drop of more than 5 points (for example B 82 to C 76) is a warning, not a cosmetic change.
- Check the last-commit date. A version pushed within the last 24 hours has had less real-world testing than one a week old.
- Note your current version and config. You need both to roll back.
Step 2 — Snapshot before you move
A snapshot turns a bad upgrade from a fire into a footnote. Do this even for a one-line version bump:
- Export your plugin config: dsh config export > backup-$(date +%F).json
- Snapshot the plugin itself if your registry supports it (deepseek-harness/backup-tool does this in one command).
- Record the exact installed version: dsh plugin list | grep <name>.
Step 3 — Update one plugin at a time
Batch updates hide the cause of a break. Update a single plugin, then verify, before the next one. For a Codex-adjacent setup, deepseek-harness/hot-reload lets you apply a config change and see the effect without a full restart, which shortens the verify loop from minutes to seconds.
Run the update, then immediately exercise the one feature you actually use. A plugin that passes its own tests can still break your specific workflow.
Step 4 — Verify after the update
- Reload config (or restart) and confirm the service comes up clean.
- Run the command you use daily; watch for changed output or new errors.
- Re-check the score. If it fell, decide now whether to keep or roll back.
Step 5 — Rollback if something breaks
If the plugin misbehaves, revert in this order:
- Restore the config snapshot: dsh config import backup-<date>.json
- Reinstall the previous version: dsh plugin install <name>@<prev-version>
- If the registry has no version pin, restore from deepseek-harness/backup-tool.
- Confirm the feature works, then report the break upstream so the next person is warned.
| Symptom | First move |
|---|---|
| Service won't start | Restore config snapshot, then downgrade |
| Config key renamed | Map old key to new name, re-import |
| Score dropped sharply | Hold the update, keep previous version |
Why a score moves after an update
A score is not a fixed grade. It recomputes from maintenance, docs, npm health, and security signals. A version that drops a README, adds an unmaintained dependency, or triggers a new security flag can fall a full band. That is why you compare the delta in Step 1 and re-check in Step 4 — the same plugin at a new version is, for scoring purposes, a different plugin.
When to skip the update
Not every new version needs you. If the changelog is documentation-only and the score held, you can wait for the next quiet afternoon. If the new version renames a config key you depend on and you have no time to remap, pin the old version and schedule the change. An upgrade you rush at 5 p.m. on a Friday is the one that breaks at 9 p.m.
Similar plugins worth checking
Two plugins make safe upgrades easier. deepseek-harness/hot-reload applies config changes without a full restart so you can confirm a new version behaves before committing. deepseek-harness/backup-tool snapshots your config so a bad upgrade is one restore away. devflow streamlines the edit-verify loop if you maintain several plugins at once.
- deepseek-harness/hot-reload — reload config without restarting
- deepseek-harness/backup-tool — one-command snapshot and restore
- devflow — faster edit-verify loop across plugins
About DSH Quality
DSH Quality scores every plugin on maintenance, docs, npm health, and security, so your upgrade decisions rest on evidence instead of guesswork. Check a plugin's score before you update at dshquality.com, read the supply-chain guide, or browse the full plugin index at /.