Contributing to Ruby Core: Fixing Encoding Crashes in the Debug Gem

はじめに (Introduction)

Ruby の debug gem にコントリビューションする機会がありました。LANG 環境変数が空の時にデバッガーがクラッシュする問題を修正しました。

I recently had the opportunity to contribute to Ruby’s debug gem by fixing a critical encoding issue that caused the debugger to crash when the LANG environment variable was empty.

問題の発見 (Problem Discovery)

異なる言語のデバッグツールを比較研究していた時のことです。C# や TypeScript での開発経験を活かしつつ、Ruby のデバッグ環境も理解を深めようと debug gem を試していました。最小限の環境でテストしていた際に LANG= を空にして Ruby デバッガーを起動したところ、突然クラッシュしました。

LANG= ruby -e 'require "debug"; debugger'
# Encoding::CompatibilityError が発生！

最初は自分のテスト環境の問題だと思いましたが、調べてみると Issue #1131 で同じ問題が報告されていることを発見しました。これは多くの開発者に影響する問題だと感じ、解決に取り組むことにしました。

While researching debugging approaches across different languages to broaden my technical perspective, I was exploring Ruby’s debug gem alongside my experience with C# and TypeScript debugging tools. During testing in a minimal environment, when I ran the Ruby debugger with LANG= (empty), it suddenly crashed.

LANG= ruby -e 'require "debug"; debugger'
# Encoding::CompatibilityError occurred!

Initially, I thought it was just my test environment setup, but after investigating, I discovered that the same issue was reported in #1131. Recognizing this as a problem affecting many developers, I decided to work on a solution.

症状 (Symptoms):

• LANG= (空) の環境でデバッガーを起動すると、UTF-8 文字を含むヒストリーファイルで Encoding::CompatibilityError が発生
• デバッガーが完全にクラッシュしてしまう
• 特に Docker や CI 環境でよく発生

The symptoms were:

• When LANG= (empty), the debugger would crash with Encoding::CompatibilityError on history files containing UTF-8 characters
• This completely broke the debugging experience
• Particularly common in Docker and CI environments

解決策の検討 (Solution Analysis)

最初は UTF-8 エンコーディングを強制する方法を考えましたが、ko1 さんからより良いアプローチの提案をいただきました：

1. システムのエンコーディング設定を尊重する
2. String#scrub を使って無効な文字を適切に処理する

Initially, I considered forcing UTF-8 encoding, but ko1-san suggested a better approach:

1. Respect system encoding preferences
2. Use String#scrub to handle invalid characters gracefully

実装内容 (Implementation)

修正は3つの箇所に適用されました：

1. ヒストリーファイルの読み込み (History File Reading)

# Before
["#{FH}#{f}".dup] + File.readlines(path)

# After  
lines = File.readlines(path).map(&:scrub)
["#{FH}#{f}".dup] + lines

2. ヒストリーファイルの書き込み (History File Writing)

# Before
f.puts line.strip

# After
scrubbed_line = line.scrub.strip
f.puts scrubbed_line

3. ヒストリーの読み込み (History Loading)

# Before
read_history_file.each{|line|
  line.strip!
  history << line unless line.empty?
}

# After
read_history_file.each{|line|
  line.scrub!
  line.strip!  
  history << line unless line.empty?
}

The fix was applied in three key areas:

1. Reading history files - scrub invalid characters before processing
2. Writing history files - ensure clean data is written
3. Loading history - handle encoding issues gracefully during runtime

String#scrub の利点 (Benefits of String#scrub)

String#scrub は Ruby の素晴らしいメソッドです：

• 無効な文字を適切に処理（デフォルトで ? に置換）
• システムクラッシュを防ぐ
• エンコーディングの互換性を保つ
• パフォーマンスへの影響が最小限

String#scrub is a fantastic Ruby method that:

• Handles invalid characters gracefully (replaces with ? by default)
• Prevents system crashes
• Maintains encoding compatibility
• Has minimal performance impact

テスト方法 (Testing)

修正後、以下のコマンドが正常に動作することを確認：

LANG= ruby -e 'require "debug"; debugger'

After the fix, this command works without crashing:

LANG= ruby -e 'require "debug"; debugger'

レビューとマージ (Review and Merge)

ko1 さんから素晴らしいフィードバックをいただき、IRB の動作との比較も含めて議論しました。最終的に PR #1144 として無事マージされました。

The PR received excellent feedback from ko1-san, including discussions about how IRB handles similar encoding issues. The fix was successfully merged as PR #1144.

学んだこと (Key Learnings)

1. 問題の根本原因を理解することの重要性
2. String#scrub のような Ruby の組み込みメソッドの力
3. システムの設定を尊重することの大切さ
4. オープンソースコミュニティでのコラボレーションの価値

Key takeaways from this contribution:

1. Understanding root causes rather than applying band-aid fixes
2. Leveraging Ruby’s built-in methods like String#scrub
3. Respecting system configurations instead of forcing assumptions
4. The value of open source collaboration and community feedback

まとめ (Conclusion)

小さな修正でしたが、多くの開発者に影響する重要な問題を解決できました。Ruby のデバッグ体験が向上し、より多くの環境で安定して動作するようになりました。

While a small fix, it addressed a critical issue affecting many developers. The Ruby debugging experience is now more robust and stable across different environments.

オープンソースへのコントリビューションは学びの宝庫です。皆さんもぜひ挑戦してみてください！

Open source contributions are incredibly rewarding learning experiences. I encourage everyone to give it a try!

リンク (Links)

• Issue #1131: Environment variable LANG is empty error
• PR #1144: Fix encoding crash when LANG environment is empty
• Ruby debug gem