UPGRADING.md

Upgrading from 1.x

country_select 2.0 has brought a few small changes, but these changes can have a big impact on existing production systems. Please read these points carefully and consider whether upgrading to 2.0 is a good idea.

Please post any implications we may have missed as a GitHub Issue or Pull Request.

ISO codes are always on

If you upgrade to 2.0 and are currently storing countries by the names produced by this gem, your setup will break. It is recommended that you stick with 1.x until developing a data migration strategy that allows you to map your existing country names to country codes.

i18n country names are always on (when available)

Country names will be generated using I18n.locale if a translation from the countries gem is available.

Codes are UPCASED

The official ISO 3166-1 standard uses UPCASED codes. This is an easy data change, but may affect areas of code dependent on lowercase country codes.

Here's a sample SQL migration that could address a users table with lowercased country codes stored in the country_code column:

UPDATE users SET country_code = UPPER(country_code);

Priority countries are now in the options hash

The priority countries syntax has changed from

  country_select(:user, :country_code, ["GB","FR"])

to

  country_select(:user, :country_code, priority_countries: ["GB","FR"])

A note on 1.x Syntax

In order to seamlessly support popular libraries dependent on country_select, specifically formatstic and simple_form, 1.x priority syntax is still supported, but will probably be removed in the next major release (i.e., 3.0). We'll be working with simple_form and formtastic maintainers to transition away from the old 1.x syntax.

You can choose to only display a chosen set of countries

  country_select(:user, :country_code, only: ["LV","SG"])

  country_select(:user, :country_code, except: ["US","GB"])

Ruby 1.9+

country_select will no longer be tested in Ruby < 1.9.