DeepSeek Harness version numbers: three parts and tags

A DeepSeek Harness version number is not one number but three pieces of information. Semantic version, prerelease tag, and build commit answer different questions; reading only the prefix leads to "the upgrade broke" or "I cannot roll back."

Three parts

Split the version before judging compatibility.

Semantic versions describe compatibility. Major changes usually mean breaking changes, minor adds features, and patch fixes (source).

Prerelease tags describe stability. A version with beta or rc may still change; it is not the stable release.

Build commits describe the exact state. Installations from source should record the commit; the same version can include multiple commits.

Semantic version and compatibility

Judge by which part changed.

1. Major change: check the changelog for breaking changes, plugin API, and configuration format.
2. Minor change: usually additive; confirm plugin compatibility.
3. Patch change: bug fixes; still confirm behavior.
4. No change but different commit: code differs; for source installs, check the commit.
5. No changelog: treat the upgrade as risky and back up first.

Major upgrades are not "a bit newer." They may change configuration and plugin interfaces; read notes and back up before upgrading.

A version number is a promise about compatibility, not about features. Feature lists live in release notes; the number only signals the level of change.

Prerelease tags

Prerelease is for trying new features, not daily stability.

1. Read the tag: beta, rc, or nightly.
2. Confirm the target: new features, bug verification, or compatibility testing.
3. Use a separate data directory and version.
4. Record issues and rollback steps.
5. Do not use prerelease for critical production.

Prerelease may change at any time. The same numeric version can move from beta.1 to beta.2 with fixes; those who need stability should wait for stable.

Mixing prerelease and stable data is risky. Data formats may differ; switching back may not read newer data.

Version and build commit

Source installs need both.

1. Record the version and commit at install.
2. Confirm the commit matches the branch.
3. Record the data directory version.
4. Use the commit to locate issues in source.
5. Rebuild by checking out the tag or commit.

Package installs emphasize the version, source installs the commit. The commit decides "which line of code," which is critical for debugging and rollback.

Do not change only one. Upgrading the package while leaving plugins on old interfaces causes mismatches.

Pinning and upgrading

Pinning is reproducibility, upgrading is acquiring change.

1. Pin the version for production or critical environments.
2. Back up the data directory before upgrading.
3. Upgrade one layer: main program, then plugins.
4. Verify sessions, plugins, and configuration.
5. Record the new version and rollback steps.

Pin first, then plan the upgrade. Production without a pinned version means every restart may bring change.

Upgrade order affects failure scope. Upgrading the main program before plugins exposes incompatibilities; doing both hides the cause.

Rollback

Rollback requires the old version, old data, and steps.

1. Confirm the previous version and commit.
2. Stop the service to prevent writes.
3. Restore the data directory backup.
4. Reinstall the old version.
5. Verify sessions and plugins.

Data format is the hard part of rollback. If a newer version rewrote data, restoring the backup matters more than reinstalling the old version.

Without a backup, "rollback" is only downgrading the program. Long sessions rewritten by newer versions will not be readable.

Reading strategy

When reading a version number, ask three questions.

1. Which part changed? Major, minor, or patch.
2. Is there a prerelease tag? Stability first.
3. Is there a commit? Source installs need it.

Answering the three decides whether to upgrade and how to roll back. Reading only the leading number hides most information.

Next steps

Split the version, check compatibility, back up first. For update versions, read How to update dsh. For prerelease choices, read How to choose a prerelease. For upgrade failures, read How to recover a failed dsh update.

Sources: DeepSeek Harness Releases, dsh CLI README, deepseek-harness repository