Contributing Data

Contributing to Carmen's Data

Many members of the community have contributed to the data set provided by Carmen. There has been some confusion about how to make changes to the data sets, and I'd like to try to clear this up.

If You Plan To Make Data Changes

All data changes should be made within either the iso_data/overlay directories or the locale/overlay directories. Carmen uses a layered data structure. It reads each layer of the data in a specific order, allowing later layers to overwrite previous ones.

The data within iso_data/base and locale/base are generated by the script/update_data.rb script from the upstream iso_data Debian project. As a result, any changes made in either directory will be overwritten during the next data import.

Carmen addresses this by providing iso_data/overlay and locale/overlay directories, which mirror the structure of the files in the base directories. The overlay directories are loaded after the base directories, so whatever is in overlay will override whatever is in base.

This arrangement allows us to benefit from changes made to the data upstream as well as contributions from the Carmen community.

To Add a Region or Subregion

Find the file you'd like to change. Let's say it is iso_data/base/world.it.yml:

---
- code: AL
  type: county
- code: KL
  type: county
- code: KU
  type: county
- code: MR
  type: county
- code: PN
  type: county
- code: SA
  type: county
- code: TA
  type: county
- code: TE
  type: county
- code: UT
  type: county
- code: VL
  type: county

To add a new region to this file, add a new file at iso_data/overlay/world/it.yml if it doesn't exist. Then, add only the new (or changed values) to this file:

---
- code: ZZ
  type: county

If you add a new region, please also add a matching entry to the locale files.

To Correct a Name

Find the file you'd like to change. Let's say it is locale/base/en/world/ls.yml:

---
en:
  world:
    ls:
      a:
        name: Maseru
      b:
        name: Butha-Buthe
      c:
        name: Leribe
      d:
        name: Berea
      e:
        name: Mafeteng
      f:
        name: Mohale's Hoek
      g:
        name: Quthing
      h:
        name: Qacha's Nek
      j:
        name: Mokhotlong
      k:
        name: Thaba-Tseka

Let's say that Quthing is actually supposed to be spelled Quthingae (it isn't, this is just an example).

To fix the spelling, add a new file at locale/overlay/en/world/ls.yml if it doesn't exist. Then, add only the new (or changed values) to this file:

---
en:
  world:
    ls:
      g:
        name: Quthingae

To Remove (Disable) a Region or Subregion

Find the file you'd like to change. Let's say it is iso_data/base/world/ke.yml:

---
- code: '110'
  type: province
- code: '200'
  type: province
- code: '300'
  type: province
- code: '400'
  type: province
- code: '500'
  type: province
- code: '700'
  type: province
- code: '800'
  type: province

To disable a subregion (region) in this file, we are going to modify the appropriate overlay file iso_data/overlay/world/ke.yml. If this overlay file does not exist, create it.

In this example we want to disable the region with code == 400. We can do this by setting the _enabled value to false:

---
- code: '400'
  _enabled: false

Verify Your Changes

Tests are welcome for code changes, but not for changes to the data sets. To test your changes manually, use the rake console command to load an IRB session with Carmen preloaded. You can then navigate using the Carmen API to verify the changes you made are having the desired effect.

➜ carmen git:(master) bundle exec rake console
irb(main):001:0> italy = Carmen::Country.coded('it')
=> <#Carmen::Country name="Italy">
irb(main):002:0> italy.subregions.map(&:name).sort
=> ["Abruzzo", "Basilicata", "Calabria", "Campania", "Emilia-Romagna", "Friuli-Venezia Giulia", "Lazio", "Liguria", "Lombardia", "Marche", "Molise", "Piemonte", "Puglia", "Sardegna", "Sicilia", "Toscana", "Trentino-Alto Adige", "Umbria", "Valle d'Aosta", "Veneto"]

Thanks for reading this document and contributing! Cheers!

If you aren't sure what files to change, give it a shot and open a pull request. I'll do my best to guide you in the right direction.