Increment Major Version vs. Deprecation Message: Choosing a NuGet Strategy for Safe Rollback After a Breaking Schema Change

Question

The goal is to allow consumers of a NuGet package to revert to a non‑breaking version after a breaking schema change without having to manually edit version constraints in their project or lock files. NuGet treats each published version as immutable, so rollback depends entirely on the consumer’s version range and any lock‑file constraints. The documented options are to increment the major version (following SemVer) and optionally unlist the old version, or to keep the same ID and version while adding a deprecation message and relying on consumers to exclude the breaking version via version ranges.

Because unlisted versions remain in local caches and broad ranges can still pull the breaking version, it is unclear which approach provides a more reliable safety net for rollback, especially when teams use lock files or continuous integration pipelines that restore from cached packages. This uncertainty raises questions about the trade‑off between explicit version bumps and deprecation messaging for ensuring that a rollback to a safe version is both discoverable and enforceable. Which strategy better prevents accidental restoration of a breaking version when local caches are present? How does each approach interact with lock‑file‑based restores to guarantee that a consumer can revert to a prior safe version without manual intervention?

Tasadduq Burney · Answer

Answer to the Core Question
When a breaking schema change is introduced, the safest way to guarantee that consumers can revert to a non‑breaking version without touching their project files is to increment the major version and pin the old release via a lock file or a strict version range. A deprecation message alone does not influence NuGet’s resolution algorithm; cached or floating‑range consumers will still pull the latest matching version, even if that version is marked as deprecated or unlisted.
Confirmed Facts (based on current SemVer practice)

NuGet treats each published version as immutable; unlisting only prevents new installs but does not remove the package from existing caches.
Lock files (packages.lock.json) capture the exact version that was restored, so a consumer can roll back by keeping the lock file unchanged.
Version ranges such as [1.0.0,2.0.0) automatically select the highest available version that satisfies the range, regardless of deprecation status.
Automatic restore from a local cache can deliver a previously downloaded breaking version if the consumer’s lock file or range allows it.

Practical Steps for This Scenario

Publish the breaking change as a new major version (e.g., 2.0.0). Include a clear release note that the schema is incompatible.
Unlist the old, safe version (e.g., 1.0.0). This stops new projects from pulling it automatically, but cached copies may still exist.
Advise consumers to use a strict version constraint or a lock file. For example, PackageReference Include="Foo" Version="1.0.0" /> or a lock file that pins to 1.0.0.
If a consumer is already using a floating range like [1.0.0,2.0.0), they will receive 2.0.0. To rollback, they must edit the csproj to reference 1.0.0 or add a lock file that pins to it.
In CI/CD pipelines, configure the restore step to use --force-include-prerelease only if you intend to test the breaking version. Otherwise, rely on the lock file or a non‑floating range to enforce the safe version.
Optionally, publish a “deprecated” or “obsolete” warning in the new major release to alert developers, but treat it as a courtesy rather than a hard block.

Additional Diagnostic Question
To tailor the recommendation further, could you confirm what version range or lock‑file strategy your projects currently use? Knowing whether they employ floating ranges, strict ranges, or lock files will clarify the exact rollback path you should adopt.

Increment Major Version vs. Deprecation Message: Choosing a NuGet Strategy for Safe Rollback After a Breaking Schema Change

1 answer

Answer to the Core Question

Confirmed Facts (based on current SemVer practice)

Practical Steps for This Scenario

Additional Diagnostic Question

Your perspective belongs here.

0 question comments