Reverting Releases

Reverting releases undoes problematic design system versions by restoring previous states. When releases cause significant issues, reversion provides faster relief than developing fixes. Understanding reversion options and procedures enables quick response to release problems.

What Is Reverting Releases

Reverting releases restores previous design system versions after a problematic release is discovered. This differs from fixing forward (publishing a new version with a fix) by going backward to known-good state rather than forward to a new state.

Reversion is appropriate when issues are severe and fixes are not immediately available. Rolling back to a working version stops the bleeding while proper fixes are developed. Reversion trades new features or fixes in the problematic version for stability.

How Reverting Releases Works

Reversion involves technical steps to restore previous versions and communication to guide consumers. Execution should be swift while maintaining quality.

Technical reversion varies by distribution method. For npm packages, pointing the latest tag to the previous version makes default installations get the older version. Publishing a new version containing the old code provides explicit reversion. Deprecating the problematic version warns consumers away.

Consumer guidance helps affected consumers recover. Clear communication explains what happened and what to do. Consumers already on the problematic version need instructions for reverting in their projects. Those not yet upgraded need to know to avoid the problematic version.

Post-reversion activities address the underlying issue. Understanding what went wrong prevents recurrence. Developing proper fixes enables eventual release of the intended changes. Communication keeps consumers informed throughout.

Key Considerations

• Act quickly when reversion is warranted
• Use the fastest effective reversion method
• Communicate clearly to affected consumers
• Investigate root cause while providing relief
• Plan proper fix development alongside reversion

Common Questions

How should consumer projects revert to previous versions?

Consumer projects can revert by explicitly specifying the previous version. For npm projects, changing the package.json version to the previous good version and running npm install restores it. Lockfiles may need updating to ensure the correct version resolves.

Guidance should be specific about version numbers. Telling consumers to use version 1.2.3 is more actionable than telling them to use the previous version. Release communications should include specific version numbers.

Consumers using exact version specifications may already be protected. If a project pins to version 1.2.2, the problematic 1.2.3 release does not affect them until they explicitly upgrade. This is one benefit of exact version pinning.

Consumers using version ranges may have automatically received the problematic version. These consumers need to explicitly pin to the older version or wait for the dist-tag update to take effect.

When should teams revert versus fix forward?

The decision between reverting and fixing forward depends on issue severity, fix timeline, and consumer impact. Several factors inform the choice.

Issue severity affects urgency. Critical issues affecting many consumers warrant immediate reversion. Minor issues affecting few consumers may allow time for fixes.

Fix timeline affects practicality. If a fix can be developed and released within hours, fixing forward may be faster than reverting and later re-releasing. If fixes require days of work, reversion provides faster relief.

Consumer impact affects preference. If reversion removes features consumers are actively using, fixing forward may be preferred despite being slower. If the problematic version is not yet widely adopted, reversion is low-impact.

Combining approaches is possible. Reverting immediately while developing a fix provides fast relief followed by proper resolution. This approach adds release overhead but optimizes consumer experience.

Summary

Reverting releases restores previous versions when releases cause significant problems. Technical reversion methods combined with clear consumer communication enable quick recovery. The decision between reverting and fixing forward depends on issue severity, fix timeline, and consumer impact.