Handle countries that have been removed from the CLDR standard (e.g: Netherlands Antilles) or changed (e.g.: Czechoslovakia (cs) => Czech (cz) | Slovakia (sk))

The problem with ISO 3166 is that using it will invalidate data that was perfectly valid in the past, once a country gets removed from the list. It's as if ISO believes that if a country no longer exists, nobody should care about it anymore.

Leave and rename the country to mark it as removed, eg: "Netherlands Antilles (historical)"

No. The country's name does not include the word "historical". This is metadata and should be handled as such.

During a quick search on the removal of countries from ISO 3166 I found the following explanations (source):

Country names might be removed from ISO 3166-1 for various reasons

• A country might change a significant part of its name, for example Burma (BU) was changed to Myanmar (MM) in 1989. The code element for the formerly used country name is therefore BUMM.
• A country may divide into two or more new ones, for example Czechoslovakia was divided into Czech Republic and Slovakia in 1993. The code element for the formerly used country name Czechoslovakia is CSHH, HH meaning that no single successor country exists.
• Two or more countries may merge for example Democratic Yemen (YD) and Yemen Arab Republic (YE) merged into the Republic of Yemen (YE) in 1990. The code element used for the formerly used country name Democratic Yemen is YDYE.

Apparently, this is where ISO 3166-3 comes in, which has four-letter country codes. This means that we can actually update old country data, but we need to find a way to do this programmatically.

Perhaps a silly idea, but it would definitely be KISS:

Why don't we simply add an additional array key along the lines of 'hidden' => TRUE for each country that no longer exists?

In other words:

1. For the UI, we add a new #type country_select (similar to the existing language_select).
   • Regular country select widgets do not show these tagged countries by default.
   • Only if the existing #default_value happens to be one of those obsolete values, then the user is forced to choose a new option/value.
2. For API-level code, the old/obsolete country data is always still accessible, so existing data can be properly mapped.
3. The update script is changed to automatically apply the additional flag to all countries/territories that are obsolete.

@sun: you are assuming that country codes are not reused. I don't know if it is true.

True. I don't know that either.

OTOH, that slightly sounds like a separate issue to me (for which there might not be any kind of solution at all, unless we'd implement a full-blown CRUD API + hooks for managing country data, so derived values that are being stored elsewhere could be updated accordingly, which would be quite a monumental stretch for something as simple as this ISO data).

I think our main focus here should be to "get rid" of the obsolete elements for new sites, while still retaining the data for backwards-compatibility.

@sun: you are assuming that country codes are not reused. I don't know if it is true.

Country codes can be reused. I don't know if this actually happened before, but the specs say that if countries cease to exist, their codes are altered from 2 letters to 4, and the old 2-letter codes are available to be reused in the future.

We are using CLDR instead of ISO for our country list now. See #1938892: Switch from ISO-3166-1 country data to CLDR unicode data

I know that this is only part of the problem, but let's see what data CLDR has for deprecated country codes (exemplary list):

There are cases where the country code simply changed for various reasons:

<territoryAlias type="BU" replacement="MM" reason="deprecated"/> <!-- Burma -->
<territoryAlias type="RH" replacement="ZW" reason="deprecated"/> <!-- CLDR:Zimbabwe -->
<territoryAlias type="UK" replacement="GB" reason="deprecated"/> <!-- CLDR: Great Britain -->
<territoryAlias type="ZR" replacement="CD" reason="deprecated"/> <!-- Zaire -->

Then there are countries that dissolved with more than one successor, a list of successors is given, sorted by population:

<territoryAlias type="AN" replacement="CW SX BQ" reason="deprecated"/> <!-- Netherlands Antilles Curaçao largest, then Sint Martin, then BQ -->
<territoryAlias type="CS" replacement="RS ME" reason="deprecated"/> <!-- Serbia & Montenegro -->
<territoryAlias type="SU" replacement="RU AM AZ BY EE GE KZ KG LV LT MD TJ TM UA UZ" reason="deprecated"/> <!-- Union of Soviet Socialist Republics -->
<territoryAlias type="YU" replacement="RS ME" reason="deprecated"/> <!-- Yugoslavia -->

Note in the case of YU -> CS -> RS/ME, that always the most current successors are given.

Then there are countries that merged to a completely new country, self-explaining:

<territoryAlias type="JT" replacement="UM" reason="deprecated"/> <!-- CLDR: Johnston Island -->
<territoryAlias type="MI" replacement="UM" reason="deprecated"/> <!-- CLDR: Midway Islands -->
<territoryAlias type="PU" replacement="UM" reason="deprecated"/> <!-- CLDR: U.S. Miscellaneous Pacific Islands -->

And countries that merged into another country (code):

<territoryAlias type="DD" replacement="DE" reason="deprecated"/> <!-- German Democratic Republic -->
<territoryAlias type="VD" replacement="VN" reason="deprecated"/> <!-- CLDR: North Vietnam -->
<territoryAlias type="YD" replacement="YE" reason="deprecated"/> <!-- Yemen, Democratic -->

More complicated is the case of a split, where one of the countries keeps the former country code.
Would be the case with Czechoslovakia (CZ) that split into Czech Republic (CZ) and Slovakia (SK).
Another case would be pre-1992 Federal Republic of Yugoslavia that lost some of its republics in 1992, before it only later completely dissolved.
For this we need the numeric territory code of the former country:

<territoryAlias type="200" replacement="CZ SK" reason="deprecated"/> <!-- Czechoslovakia -->
<territoryAlias type="280" replacement="DE" reason="deprecated"/> <!-- West Germany (pre-1990) -->
<territoryAlias type="532" replacement="CW SX BQ" reason="deprecated"/> <!-- Netherlands Antilles (pre-1986) -->
<territoryAlias type="886" replacement="YE" reason="deprecated"/> <!-- Yemen (pre-1990) -->
<territoryAlias type="890" replacement="RS ME SI HR MK BA" reason="deprecated"/> <!-- Yugoslavia (pre-1992) -->

Note also that with the numeric code data we can continue tracking the territory of former West Germany (= the former territory of the "DE" country code). Why would we want to throw away data that we have? Core might not need the distinction anymore, but contrib might require it.

Now, while territoryAlias data resides in supplementalData.xml, the full list of numerical codes resides in supplementalMetadata.xml.

See some exemplary entries:

<territoryCodes type="CZ" numeric="203" alpha3="CZE" fips10="EZ"/>
<territoryCodes type="DD" numeric="278" alpha3="DDR"/>
<territoryCodes type="DE" numeric="276" alpha3="DEU" fips10="GM"/>
<territoryCodes type="SK" numeric="703" alpha3="SVK" fips10="LO"/>

So if you combine this with the replacement dataset, you can see that DE (280) & DD (278) merged into DE (276).
And you can see that CZ (200) split into CZ (203) and SK (703).

Conclusion:

So actually we have everything we need we can update our countries list at any time without losing data (Netherlands Antilles => /dev/null), without falsifying data (Czechoslovakia => Czech Republic) and without diminishing data (West Germany => post-1990-Germany).
However, we need to store the 3-digit ISO 3166-1 numeric code that will always change when the territory changes and will never be reassigned.

A key question that needs to be answered is what happens with CountryManager::getStandardList(). Should codes be removed from this or not?

standard_country_list() is obsolete. Are there any functions besides getStandardList() which are related to this issue?

Updating this to 9.3.x as the issue is still present in Drupal 9. I guess for country codes like "cz" (Czech), see above, we could rate this as bug. But I'm not the right one to decide that.

Concrete example: We have a customer in Czech republic who is quite unhappy with the old "CS" (Display) / "cs" (language shorthand) still being used and displayed. Drupal makes a bad impression here in those countries.

@Alan D. documented the situation for Czech very well in this contries module issue: #3117578: Czechia, Slovakia and North Macedonia