---
title: "Introducing the Deprecation Toolkit"
description: "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."
---

# Introducing the Deprecation Toolkit

[Shopify](https://yomu.fyi/company/shopify) · Edouard CHIN · Sep 19, 2018

**Type:** Announcement

## 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.

**Tags:** [Refactoring](https://yomu.fyi/topic/refactoring), [Ruby](https://yomu.fyi/topic/ruby), [Testing](https://yomu.fyi/topic/testing)

- Source: [Shopify](https://shopify.engineering/introducing-the-deprecation-toolkit)
- Source URL: https://shopify.engineering/introducing-the-deprecation-toolkit
- Ingested by Yomu: 2026-09-17T14:12:51.708Z

[Read original post](https://shopify.engineering/introducing-the-deprecation-toolkit)