Loading post…
ShopifyEdouard CHINAnnouncement
Introducing the Deprecation Toolkit
Summary
Shopify’s Deprecation Toolkit is an open-source Ruby gem for tracking deprecated code in an application and preventing new deprecations from entering a codebase. It addresses the limits of warning messages and the impracticality of immediately raising on every existing deprecation, especially in a large monolith with complex dependency upgrades. The toolkit records deprecations triggered by test suites in YAML whitelist files, then compares later test runs with the accepted set; mismatches trigger configurable behavior, raising an error by default. Existing deprecations can therefore remain acceptable while teams fix them gradually, whereas introduced or removed deprecations are surfaced in CI. Shopify reports that using the toolkit reduced deprecations, supported dependency upgrades, blocked pull requests introducing new ones, and enabled team-based tracking of remediation progress.
Context
Shopify developed the toolkit after attempts to prevent developers in its monolith from accidentally using deprecated library or application code. The goal was to support gradual remediation while making dependency upgrades easier to manage.
Approach / What changed
The gem records deprecations triggered during test suites in YAML files that act as a whitelist. On later test runs, it compares observed deprecations with the accepted set and invokes configured behavior for mismatches, raising an error by default; options include ignoring selected deprecations, choosing recording locations dynamically, and defining custom behaviors.
Takeaways
Existing deprecations are recorded in YAML whitelist files so they can remain acceptable while teams fix them gradually.
A mismatch between recorded and observed deprecations can represent either an introduced or removed deprecation and triggers configured behavior, with errors as the default.
Shopify used component ownership and shared progress tracking to gamify remediation, while pull requests introducing new deprecations were prevented from merging.
FAQ
Why not simply configure every deprecation to raise an error?
Raising on every deprecation would require fixing all existing occurrences before enabling the configuration. That could block CI and developers’ daily work, so the toolkit treats recorded deprecations as acceptable while new mismatches raise errors by default.
How does the toolkit identify a new deprecation?
It records deprecations triggered by a test run and compares later test results with the YAML whitelist. If the observed set differs from the accepted set, the toolkit invokes the configured behavior.
What can be customized in the toolkit?
The toolkit can ignore selected deprecations, dynamically determine where deprecations are recorded, and use custom behaviors when new deprecations are introduced. It also provides configuration options beyond its default behavior.
Source and freshness
- Source
- shopify.engineering
- Published
- Added to Yomu
Summaries are generated from the original by a language model. Check the original before relying on it.
Keep reading
Related reading
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
The best engineering reads, once a week
One useful email. Unsubscribe anytime.