Proses untuk memperbarui ID OCD

Pengantar

Open Civic Data Identifier (OCD ID) adalah format ID umum yang menentukan wilayah geografis politik. Untuk membuat feed CDF, Anda harus memberikan ID ini sebagai bagian dari entity GpUnit. Dokumen ini bertujuan untuk memberikan panduan dan praktik terbaik untuk menambahkan ID OCD ke repositori GitHub opencivicdata.

Cara memperbarui ID OCD di repositori Open Civic Data GitHub

Prasyarat

  1. Memahami cara berkontribusi ke project open source

Sebelum memulai:

  1. Siapkan workstation Anda:

    Lakukan fork dan clone paket dari repo OSD ID.

  2. Pahami repo dengan baik:

    Dalam repo OCD ID, setiap negara yang didukung diwakili dengan direktori dan file CSV dengan nama yang sama: country-<2 letter country code> (Contoh: identifiers/country-de dan identifiers/country-de.csv untuk Jerman).

    Di dalam direktori negara yang ingin diubah, Anda dapat menemukan file CSV (Contoh) yang menyertakan bagian file CSV tingkat atas khusus negara. Ini adalah file yang perlu Anda ubah.

  3. Cara membuat ID OCD baru:

    Struktur dan sumber

    Baca dokumen data kemasyarakatan terbuka untuk memahami struktur ID OCD. Secara umum, ID OCD yang valid memiliki format berikut: ocd-division/country:<country_code>(/<type>:<type_id>)

    Penamaan ID lebih memilih ID standar dari ISO, atau standar lainnya, seperti FIPS dan NUTS, jika ISO tidak tersedia.

    Kebijakan umum

    Berikut adalah kebijakan umum:

    Hierarki

    Hierarki ID OCD harus ditentukan oleh tingkat administratif yang mengontrol batas ID OCD, tidak harus hubungan pembatasan ID OCD.

    • Contoh: Di Amerika Serikat, distrik kongres digunakan dalam pemilu untuk Dewan Perwakilan Rakyat nasional, tetapi batas-batasnya ditentukan oleh Negara Bagian. Jadi distrik kongres bergantung pada negara bagian: ocd-division/country:us/state:pa/cd:2
    • Contoh: Murryville adalah kotamadya di Pennsylvania dan berada di dalam Westmoreland County. Namun, kota dikelola oleh Negara Bagian, sehingga ID OCD bergantung pada status: ocd-division/country:us/state:pa/place:murrysville Hierarki tambahan dapat digunakan jika disambiguasi diperlukan.
    • Contoh: Ada 16 tempat di Pennsylvania yang bernama "Franklin Township". Biasanya, masing-masing akan memiliki ID OCD ocd-division/country:us/state:pa/place:franklin, tetapi akan jadi ambigu. Jadi, kita dapat menambahkan county ke ID OCD sehingga masing-masing mendapatkan ID OCD uniknya sendiri. Contoh: ocd-division/country:us/state:pa/county:adams/place:franklin
    Jenis

    • Jenis ID OCD biasanya spesifik untuk negara.

    • Beberapa ID OCD bersifat umum di seluruh repositori seperti country, region, dan place.

    • Namun, panduan umumnya adalah memilih untuk menentukan jenis dengan cara yang lebih spesifik yang sesuai dengan konteks negara tersebut.

      • Contoh: Untuk Area Admin 1 di AS, jenis state, district, dan territory digunakan.
      • Contoh: Untuk Area Admin 1 di CA, jenis province dan territory digunakan.
      • Contoh: Untuk Area Admin 1 di PT, jenis region dan autonomous_region digunakan.
    ID
    • Secara umum, kami ingin menggunakan ID OCD yang sama untuk sebuah distrik di seluruh distrik. Saat memilih type_id yang akan digunakan untuk kumpulan ID OCD baru, pilih salah satu yang paling stabil. Beberapa pertanyaan yang perlu diajukan saat menentukan ID yang akan digunakan adalah:
    • Seberapa besar kemungkinan ID untuk distrik tertentu berubah karena penetapan ulang distrik?
    • Jika pejabat yang sama memegang distrik X sebelum dan sesudah batasnya berubah dari penetapan ulang distrik, apakah saya akan menyatakan masa jabatan mereka sebagai berkelanjutan?
    • Apakah distrik dengan batas atau nama yang identik di seluruh distrik ditampilkan oleh ID yang sama?
      • Contoh: Di AS, nomor distrik kongres digunakan untuk distrik rumah AS karena meskipun batasnya berubah dengan penetapan ulang distrik, identitasnya terkait erat dengan nomor tersebut dan Anda akan menyebut seseorang sebagai penanggung jawab untuk kursi ke-N selama X tahun meskipun jumlah tahun tersebut melintasi batas distrik baru.
      • Contoh: Di Kanada, kami ingin menggunakan nama distrik untuk mewakili distrik pemilu federal karena meskipun ada kode pemilu federal, ID ini tidak stabil karena distrik yang identik di seluruh distrik direpresentasikan dengan ID yang berbeda. (misalnya, distrik 47012 sebelum tahun 2012 bukan lagi distrik yang sama setelahnya).
    Penetapan ulang distrik

    Secara umum, saat memperbarui ID OCD karena penetapan ulang distrik, gunakan kumpulan ID OCD yang sudah ada, bukan membuat kumpulan baru.

    • Jika identitas distrik (ID numerik, nama, dll.) tidak berubah setelah distrik diterapkan, gunakan ID OCD yang sama.
    • Untuk pembuatan distrik baru setelah penetapan ulang distrik, buat ID OCD baru.
    • Untuk distrik yang sudah tidak ada, perbarui kolom ValidThrough dengan tanggal penetapan ulang distrik diterapkan.
    • Jika ID distrik didasarkan pada namanya, dan nama distrik diganti setelah penetapan ulang distrik, buat ID baru berdasarkan nama distrik baru dan tambahkan alias dengan id = oldId dan sameAs = newId. Tindakan ini akan mengkanonikalisasi newId sebagai penggunaan peta oldId ke newId.
    • Jika terjadi konflik antara ID OCD historis, seperti ID baru yang identik dengan ID yang dihapus, tambahkan tahun ValidFrom ke ID baru. Untuk informasi selengkapnya tentang kebijakan penamaan ini, lihat Membuat file baru untuk ID OCD yang saat ini, dihapus, dan diganti namanya.

Perbarui salinan lokal Anda

Pembaruan apa pun harus dilakukan di direktori khusus negara: ocd-repository/identifiers/country-<2 letter country code>. Jika belum ada, buat pembaruan.

  • Jika file CSV ID OCD sudah ada dan mewakili batas pemilu yang lama, Anda perlu memperbarui file ini untuk menyertakan konstituen baru. Untuk melakukannya, tambahkan kolom ValidFrom dan ValidTo yang berisi tanggal dalam format YYYY-MM-DD.
    • ValidFrom harus merupakan tanggal pemilihan untuk konstituensi baru. Tanggal ini dapat dikosongkan untuk konstituensi yang sudah ada.
    • ValidTo untuk konstituen lama harus sehari sebelum pemilu.

Perbarui Alias

Aliasing dapat digunakan untuk menandai ID OCD sebagai representasi bagian geografi politik yang sama.

  • Misalnya, jika suatu tempat berupa kota dan kabupaten, hal ini bisa masuk akal.

Prinsip umum yang ingin kami terapkan:

  • Jika dua bagian geografi politik berbeda-beda, tidak boleh dialiaskan satu sama lain. Misalnya: kongres AS berskala besar berdekatan dengan negara bagian, tetapi ini kebetulan karena jumlah populasi AS saat ini.

Aliasing juga dapat masuk akal jika perubahan signifikan dalam perubahan hukum/konstitusional diperlukan untuk membagi distrik.

  • Misalnya, senat negara bagian Washington dan distrik dewan negara bagian ditetapkan agar sama menurut hukum konstitusi.

Jika perlu, tambahkan file CSV aliases.csv tempat kami menambahkan ID OCD lama dan aliasnya. ID kanonis dapat menggunakan jenis pembagian yang memiliki makna lokal dan dapat memiliki alias dengan representasi yang lebih dikenal (seperti, kanonis: alias ocd-division/country:de/land: `ocd-division/country:de/state). Lihat masalah #170 untuk informasi selengkapnya.

Untuk memperbarui file alias.csv:

  • Ikuti urutan kolom dalam file alias.csv: id,sameAs,sameAsNote
Jenis Deskripsi
id Kolom ini harus memiliki alias untuk ID OCD.
sameAs Kolom ini harus memiliki ID OCD aktual yang kami tambahkan alias.
sameAsNote Catatan yang menjelaskan bagaimana atau mengapa pembagian tersebut memiliki beberapa ID.

Contoh: identifiers/country-in/aliases.csv

Jalankan skrip - compile.py

Jalankan skrip python di lokasi opencivicdata/ocd-division-ids/scripts:

  • Anda harus menentukan kode negara 2 huruf sebagai argumen ke skrip agar skrip mengetahui ID negara mana yang perlu diperbarui.
  • Contoh: skrip python3/compile.py in (untuk memperbarui ID konstituen OCD di India).
  • Python 2.x tidak menerima dukungan. Harus menggunakan Python 3 atau versi yang lebih baru. Anda dapat mendownload Python 3 versi terbaru di sini.

Skrip ini mengambil data dari file CSV yang diupdate pada langkah sebelumnya (ocd-division-ids/identifiers/country-in/*.csv), memvalidasi nilai dalam file, memeriksa error data (penggunaan karakter khusus, dll.), atau duplikasi data, dan menulis ID OCD baru ke file CSV negara tingkat atas.

Skrip akan menampilkan pesan peringatan dan error jika muncul masalah dalam file CSV yang diperbarui. Selesaikan masalahnya dan jalankan skrip lagi.

Menambahkan file readme

Saat Anda menambahkan negara baru atau tingkat cakupan baru (misalnya, sebelumnya kami hanya memiliki ID OCD untuk negara tersebut, tetapi sekarang menambahkan distrik administratif tingkat pertama), tambahkan atau perbarui file README.md. File ini harus berisi garis besar singkat tentang geografi politik, termasuk:

  • Jenis yang akan kita gunakan dan perannya (seperti "districts adalah wilayah administratif tingkat pertama di negara ini");
  • Hubungan antarjenis (seperti "daerah legislatif ditetapkan dengan basis per distrik dan tidak melintasi batas distrik");
  • Semua pengecualian penting (seperti, "ada satu distrik legislatif yang mencakup semua warga asing"); dan
  • Tautkan ke halaman Wikipedia yang berguna untuk membantu memberikan konteks bagi pengulas atau pengguna.

Membuat permintaan pull

Untuk membuat permintaan pull, gunakan panduan berikut:

  • Setelah proses ini selesai tanpa error, periksa file .csv tingkat atas yang baru ditulis country-<2 letter country code>.csv untuk memastikan file tersebut sekarang menyertakan kumpulan ID OCD yang diperbarui/baru.
  • Membuat permintaan pull dan menambahkan peninjau. Permintaan pull ini harus menyertakan modifikasi yang dilakukan di semua file CSV berikut.
  • File CSV dalam direktori khusus negara. Contoh
  • File .csv negara tingkat teratas-<2 huruf kode negara>. Contoh
  • Saat ditinjau dan disetujui oleh dua committer negara, permintaan pull akan digabungkan oleh salah satu pemilik/kolaborator paket.