In Ruby 3.x and 4.0, why are deprecation warnings hidden by default, and how do you surface them with -W:deprecated or Warning[:deprecated]?

## Warning categories Ruby sorts many of its own warnings into **categories**, and each category has an on/off switch readable with `Warning[category]` and settable with `Warning[category] = flag`. `Warning.categories` (added in 3.4) lists them; Ruby 4.0 has `:deprecated`, `:experimental`, `:performance` and `:strict_unused_block`. The defaults with no flags are: | Category | Default | Typical content | |---|---|---| | `:deprecated` | `false` | APIs and behaviours scheduled for removal | | `:experimental` | `true` | experimental features such as Ractor | | `:performance` | `false` | patterns that defeat optimisations | An unknown name is an error, not `false`: `Warning[:deprecation]` raises `ArgumentError` ("unknown category"), because the category is `:deprecated`. ## Why deprecations are hidden by default Deprecation warnings used to print by default, and Ruby 2.7's keyword-argument transition showed the cost: applications and command-line tools sprayed warnings about code inside their dependencies at people who could do nothing about them. **Since Ruby 2.7.2 they are off by default**, and the 3.0 release notes repeat the rule. The consequence is that nobody sees them unless a developer asks, and many teams discover a removal only when an upgrade turns a silent deprecation into an error. The chilled-string warning, about mutating a string literal that a future Ruby will freeze, is in this category too, so it stays invisible until you opt in. ## Turning them on Pick the switch that matches the scope you need: - `ruby -W:deprecated app.rb` - enables only deprecation warnings. `-W:no-deprecated` turns them off again. - `ruby -w app.rb` - verbose mode: sets `$VERBOSE` to `true` and enables all the default categories, including deprecations, plus many other warnings. - `RUBYOPT="-W:deprecated" bundle exec rake test` - applies to every Ruby process the command starts, including child processes, without editing code. - `Warning[:deprecated] = true` - from Ruby code, typically as the first line of `test_helper.rb` or `spec_helper.rb`, so every test run shows them. `-W0` goes the other way: it silences warnings entirely, including `Kernel#warn` output, so it hides exactly what you are looking for. ## Making deprecations fail the build Printing is not enough in a large suite; people stop reading. Ruby routes every warning through **`Warning.warn`**, and its documentation says to customise it by extending the module, not by redefining the instance method: ```ruby module FailOnDeprecation def warn(message, category: nil, **kwargs) raise message if category == :deprecated super end end Warning[:deprecated] = true Warning.extend(FailOnDeprecation) ``` Calling `super` keeps normal printing for everything else. A common refinement is an allow-list of messages from gems you cannot fix yet, so the rule applies to your own code first. ## Emitting your own deprecations Library code should use the same channel: `warn "Payroll::Report#total is deprecated; use #gross", category: :deprecated, uplevel: 1`. `Kernel#warn` with a category prints only when that category is enabled, so your users get the same opt-in behaviour as Ruby's own warnings, and `uplevel: 1` points the message at the caller's line. ## A workflow for a noisy suite Turning the category on in an old codebase can print hundreds of lines. A sequence that keeps the work manageable: 1. **Collect.** Enable `Warning[:deprecated]` in the test helper and log every distinct message with its file and line. 2. **Sort by owner.** Split messages coming from your own code from those coming from installed gems; the path in each message tells you which. 3. **Fix your own code first.** These are usually mechanical: a renamed method, a literal that is mutated, a removed argument form. 4. **Upgrade or report gems.** Most gem warnings disappear with a newer gem release; for the rest, open an issue upstream. 5. **Flip to failing.** Once the list is short, extend `Warning` to raise on `:deprecated`, with an allow-list for the remaining third-party messages, and shrink that list over time. ## Where this sits in an upgrade Before moving a service to the next Ruby, run its suite on the **current** version with deprecation warnings on and fix what appears. Most removals in the 3.x line were deprecated first, so this is the cheapest early-warning system an upgrade has. Warnings about libraries leaving the default gems are a separate mechanism: they are printed through plain `Kernel#warn`, with no category, so they appear even without `-W:deprecated`.