`on_booted`/`on_restart`/`on_stopped` の廃止をPuma v9へ延期

2026年05月27日 07:16 JST puma/puma

Puma v8で削除予定だった非推奨コールバック on_booted/on_restart/on_stopped の廃止をv9に延期し、警告メッセージの明確化とバージョンガードテストを追加しました。

背景

on_booted/on_restart/on_stopped の3つのコールバックはv8での削除が予定されていましたが、実際にはv8でも削除されずにリリースされてしまいました。今回のPR #3938 はこの事態を受けて、廃止予定バージョンをv9に改め、次回の削除漏れを防ぐための仕組みを導入しています。

技術的な変更

変更は lib/puma.rb の警告メッセージの修正と、test/test_events.rb へのバージョンガードテストの追加の2点です。

警告メッセージの修正として、deprecate_method_change メソッドが出力する文言が更新されました。「v8」という曖昧な表記から「Puma v9」という明示的な表記に変わり、どのソフトウェアのバージョンを指しているかが一目でわかるようになっています。

変更前:

warn "Use '#{method_new}', '#{method_caller}' is deprecated and will be removed in v8"

変更後:

warn "Use '#{method_new}', '#{method_caller}' is deprecated and will be removed in Puma v9"

バージョンガードテストの追加として、test/test_events.rb に test_deprecated_event_methods_are_removed_in_v9 が新設されました。このテストは Gem::Version を使って現在の PUMA_VERSION が9以上かどうかを検証し、v9に到達した時点でテストが失敗することで開発者に削除作業を促します。

def test_deprecated_event_methods_are_removed_in_v9
  refute_operator Gem::Version.new(Puma::Const::PUMA_VERSION), :>=, Gem::Version.new("9"),
    "Remove deprecated on_booted/on_restart/on_stopped from Puma::Events and their tests"
end

テストファイルの先頭には require 'puma/const' も追加され、PUMA_VERSION 定数への参照が正しく解決されます。

設計判断

バージョンガードテストによる「削除漏れ防止」 という手法が採用されました。

v8での削除漏れという過去の教訓を踏まえ、単にドキュメントやコメントを更新するだけでなく、CI上でバージョン到達時に自動的に失敗するテストを仕掛けることで、人的なチェックに頼らない仕組みが組み込まれています。refute_operator と Gem::Version の比較を組み合わせることで、メジャーバージョンアップ時に必ずテストスイートが警告を発する設計です。

また、警告メッセージへの「Puma」という製品名の追記は、ユーザーがログ中に断片的なメッセージを見た際に文脈を失わないようにするための改善です。v8 という記述はどのライブラリのv8か判断できませんが、Puma v9 であれば出所が明確です。

まとめ

廃止時期の延期そのものは小さな変更ですが、バージョンガードテストの導入によって「次こそ削除し忘れない」という仕組みが自動化された点が本PRの本質的な価値です。非推奨機能の段階的廃止において、将来の作業をテストで強制するこのパターンは、長期メンテナンスにおける実践的な手法として参考になります。