Last Updated: 2024-11-23

I updated a gem (Ruby package) from v2.x to v3.x. This had major breaking changes and I couldn't easily figure out how to upgrade my code. In particular, I had no intention of wading through their READMEs.

Luckily there are tools that compare versions of the gem code. In Ruby, this is yard, a documentation tool. It displays what objects and methods were added, modified, or removed:

$ yard diff countries-2.1.4 countries-3.0.0

=> Added objects:

  ISO3166::Configuration#enable_currency_extension! (lib/countries/configuration.rb:27)
  ISO3166::CountryClassMethods#create_subdivisions (lib/countries/country/class_methods.rb:92)
  ISO3166::CountryClassMethods#subdivision_data (lib/countries/country/class_methods.rb:140)
  ISO3166::CountryClassMethods#subdivision_file_path (lib/countries/country/class_methods.rb:145)
  ISO3166::CountryClassMethods#subdivisions (lib/countries/country/class_methods.rb:87)
  ISO3166::CountryCurrencyMethods (lib/countries/country/currency_methods.rb:5) (...)

Modified objects:

  Countries::VERSION (lib/countries/version.rb:2)
  ISO3166::Country#states (lib/countries/country.rb:72)
  ISO3166::Country#subdivision_names_with_codes (lib/countries/country.rb:68)
  ISO3166::Country#subdivisions (lib/countries/country.rb:62)
  ISO3166::Country#subdivisions? (lib/countries/country.rb:58)

Removed objects:

  ISO3166::Country#currency (lib/countries/country.rb:50)
  ISO3166::Country#subdivision_data (lib/countries/country.rb:116)
  ISO3166::Country#subdivision_file_path (lib/countries/country.rb:124)

My workflow then was to cross-reference with my own codebase to see how I was using their library. E.g. I searched for IS031 references:

$ ag ISO31 -G app 
# -G limits ag to searching in files matching that pattern

app/models/utilities/country_names.rb
20:      ISO3166::Country[store].currency.iso_code
...

Scanning this output, I see the currency method, which was removed, might be an issue. Running the code confirms it was in fact broken.