กระบวนการอัปเดตรหัส OCD

เกริ่นนำ

Open Civic Data Identifier (รหัส OCD) เป็นรูปแบบตัวระบุที่ใช้กันทั่วไปซึ่งระบุพื้นที่ทางการเมือง หากต้องการสร้างฟีด CDF คุณต้องระบุตัวระบุเหล่านี้เป็นส่วนหนึ่งของเอนทิตี GpUnit เอกสารฉบับนี้มีจุดประสงค์เพื่อให้คำแนะนำและแนวทางปฏิบัติแนะนำในการเพิ่มรหัส OCD ในที่เก็บ Opencivicdata GitHub

วิธีอัปเดตรหัส OCD ในที่เก็บ Open Civic Data GitHub

ข้อกำหนดเบื้องต้น

  1. ทำความเข้าใจวิธีมีส่วนร่วมกับโครงการโอเพนซอร์ส

ก่อนจะเริ่ม

  1. เตรียมเวิร์กสเตชันดังนี้

    แยกและโคลนแพ็กเกจจากที่เก็บรหัส OCD

  2. ทำความคุ้นเคยกับที่เก็บ:

    ในที่เก็บรหัส OCD ประเทศที่รองรับแต่ละประเทศจะแสดงในรูปแบบไดเรกทอรีและไฟล์ CSV ที่ใช้ชื่อเดียวกัน เช่น country-<2 Letter country code> (เช่น identifiers/country-de และ identifiers/country-de.csv สําหรับเยอรมนี)

    ในไดเรกทอรีของประเทศที่คุณต้องการแก้ไข คุณสามารถค้นหาไฟล์ CSV (ตัวอย่าง) ที่มีส่วนต่างๆ ของไฟล์ CSV เฉพาะประเทศระดับบนสุด ซึ่งเป็นไฟล์ที่คุณจะต้องแก้ไข

  3. วิธีสร้างรหัส OCD ใหม่

    โครงสร้างและแหล่งที่มา

    ดูเอกสารข้อมูลพลเมืองแบบเปิดเพื่อทำความคุ้นเคยกับโครงสร้างรหัส OCD โดยทั่วไปแล้ว OCD ID ที่ถูกต้องจะอยู่ในรูปแบบต่อไปนี้ ocd-division/country:<country_code>(/<type>:<type_id>)

    การตั้งชื่อตัวระบุจะชอบตัวระบุมาตรฐานจาก ISO หรือมาตรฐานอื่นๆ เช่น FIPS และ NUTS หากไม่มี ISO

    นโยบายทั่วไป

    นโยบายทั่วไปมีดังนี้

    ลำดับชั้น

    ลำดับชั้นของรหัส OCD ต้องเป็นไปตามระดับการดูแลระบบที่ควบคุมขอบเขตของรหัส OCD โดยไม่จําเป็นต้องเป็นความสัมพันธ์การยับยั้งของรหัส OCD

    • ตัวอย่าง: ในสหรัฐอเมริกามีการใช้เขตเลือกตั้งในการเลือกตั้งสภาผู้แทนราษฎร แต่เป็นการกำหนดขอบเขตโดยสหรัฐอเมริกา เขตเลือกตั้งของพรรคต่างๆ อาจไปอยู่นอกเขตเลือกตั้ง เช่น ocd-division/country:us/state:pa/cd:2
    • ตัวอย่าง: Murrysville เป็นเขตปกครองในรัฐเพนซิลเวเนียและอยู่ในเทศมณฑลเวสต์มอร์แลนด์ อย่างไรก็ตาม เมืองต่างๆ อยู่ภายใต้การปกครองโดยรัฐ ดังนั้นรหัส OCD จะไม่เชื่อมโยงกับรัฐ: ocd-division/country:us/state:pa/place:murrysville อาจมีการใช้ลำดับชั้นเพิ่มเติมในกรณีที่จำเป็นต้องชี้แจง
    • ตัวอย่าง: มีสถานที่ 16 แห่งในเพนซิลเวเนียที่ชื่อ "FranklinTownship" โดยปกติ แต่ละรายการจะมีรหัส OCD ocd-division/country:us/state:pa/place:franklin แต่จะมีความชัดเจน เราจึงสามารถเพิ่มเขตลงในรหัส OCD แทนได้เพื่อให้แต่ละรหัสมีรหัส OCD เป็นของตัวเอง เช่น ocd-division/country:us/state:pa/county:adams/place:franklin
    Type

    • โดยทั่วไปแล้วประเภทรหัส OCD จะเป็นประเภทที่เฉพาะเจาะจงสำหรับประเทศ

    • รหัส OCD บางรายการเป็นรหัสทั่วไปในที่เก็บ เช่น country, region และ place

    • อย่างไรก็ตาม คำแนะนำทั่วไปคือการลองระบุประเภทของประเภทที่เฉพาะเจาะจงมากขึ้นซึ่งน่าจะเข้าใจได้ในบริบทของประเทศนั้น

      • ตัวอย่าง: สำหรับเขตบริหาร 1 ในสหรัฐอเมริกา ระบบจะใช้ประเภท state, district และ territory
      • ตัวอย่าง: สำหรับพื้นที่ผู้ดูแลระบบ 1 ใน CA จะใช้ประเภท province และ territory
      • ตัวอย่าง: สำหรับพื้นที่ผู้ดูแลระบบ 1 ใน PT จะใช้ประเภท region และ autonomous_region
    ID
    • โดยทั่วไป เราต้องการใช้รหัส OCD เดียวกันสำหรับเขตการศึกษาในเขตใหม่ เมื่อเลือก type_id เพื่อใช้กับรหัส OCD ชุดใหม่ ให้เลือกรหัสที่เสถียรที่สุด คำถามที่ควรถามเมื่อพิจารณาว่าจะใช้ตัวระบุใดมีดังนี้
    • ตัวระบุของเขตการศึกษานั้นๆ มีแนวโน้มมากน้อยเพียงใดที่จะมีการเปลี่ยนแปลงเนื่องจากมีการแบ่งเขตใหม่
    • หากผู้ดำรงตำแหน่งทางการเมืองคนเดียวกันถือเขต X ก่อนและหลังจากขอบเขตเขตของเขตเดิมไปแล้ว ฉันจะเป็นตัวแทนอย่างต่อเนื่องของเขต X หรือไม่
    • เขตการศึกษาที่มีชื่อเขตเดียวกันเหมือนกันทั้งหมดในเขตพื้นที่ใหม่ มีการระบุด้วยตัวระบุเดียวกันไหม
      • ตัวอย่าง: ในสหรัฐอเมริกาจะใช้หมายเลขเขตเลือกตั้งสำหรับเขตสภาผู้แทนราษฎรของสหรัฐอเมริกา เพราะถึงแม้ขอบเขตจะเปลี่ยนไปด้วยการกำหนดเขตใหม่ แต่ข้อมูลประจำตัวจะยึดติดกับหมายเลขนั้นอย่างแน่นแฟ้น และคุณจะหมายถึงว่าผู้อื่นถือครองตำแหน่งที่นั่งที่ N เป็นเวลา X ปี แม้ว่าจำนวนปีดังกล่าวจะข้ามขอบเขตใหม่ก็ตาม
      • ตัวอย่าง: ในแคนาดา เราต้องการใช้ชื่อเขตเพื่อแสดงถึงเขตเลือกตั้งระดับรัฐบาลกลาง เนื่องจากถึงแม้รหัสการเลือกตั้งระดับรัฐบาลกลางจะมีอยู่ แต่ตัวระบุนี้ไม่คงที่เนื่องจากเขตเดียวกันในเขตการศึกษาใหม่จะแสดงรหัสต่างกัน (เช่น เขต 47012 ก่อนการกำหนดเขตใหม่ปี 2012 จะไม่เป็นเขตการศึกษาเดียวกันในภายหลัง)
    การแบ่งขอบเขตซ้ำ

    โดยทั่วไปแล้ว เมื่ออัปเดตรหัส OCD เนื่องจากมีการจำแนกขอบเขตใหม่ ให้ใช้ชุดรหัส OCD ที่มีอยู่แทนการสร้างชุดใหม่

    • หากข้อมูลประจำตัวของเขตการศึกษา (รหัสตัวเลข ชื่อ ฯลฯ) ไม่เปลี่ยนแปลงหลังจากการกำหนดเขตใหม่ ให้ใช้รหัส OCD เดียวกัน
    • สำหรับการสร้างเขตใหม่หลังจากกำหนดเขตใหม่ ให้สร้าง OCD ID ใหม่
    • สำหรับเขตที่ไม่มีอยู่อีกต่อไป ให้อัปเดตช่อง ValidThrough โดยเปลี่ยนวันที่ที่มีผลบังคับใช้แล้ว
    • หากรหัสของเขตมาจากชื่อเขตและมีการเปลี่ยนชื่อเขตหลังจากการแบ่งเขตใหม่ ให้สร้างรหัสใหม่โดยอิงตามชื่อเขตใหม่ และเพิ่มชื่อแทนที่ id = oldId และ sameAs = newId ซึ่งจะกำหนด newId เป็นการใช้งานของ oldId แมปกับ newId
    • ในกรณีที่มีความขัดแย้งระหว่างรหัส OCD ที่ผ่านมา เช่น รหัสใหม่เหมือนกับรหัสที่ยกเลิกไปแล้ว ให้เพิ่มปี ValidFrom ต่อท้ายรหัสใหม่ ดูข้อมูลเพิ่มเติมเกี่ยวกับนโยบายการตั้งชื่อนี้ได้ที่สร้างไฟล์ใหม่สำหรับ OCD-ID ในปัจจุบัน ที่ยกเลิกไปแล้ว และที่เปลี่ยนชื่อ

อัปเดตสำเนาในเครื่องของคุณ

ต้องอัปเดตภายในไดเรกทอรีเฉพาะประเทศ ocd-repository/identifiers/country-<2 ตัวอักษรรหัสประเทศ> หากยังไม่มี ให้สร้างขึ้นมา

  • หากมีไฟล์ CSV ของรหัส OCD อยู่แล้วและแสดงเขตการเลือกตั้งเก่า คุณจะต้องอัปเดตไฟล์นี้เพื่อรวมเขตเลือกตั้งใหม่ ในการดำเนินการนี้ ให้เพิ่มคอลัมน์ ValidFrom และ ValidTo ที่มีวันที่ในรูปแบบ YYYY-MM-DD
    • ValidFrom ควรเป็นวันเลือกตั้งสำหรับเขตเลือกตั้งใหม่ ซึ่งสามารถเว้นว่างไว้ได้สำหรับเขตเลือกตั้งที่มีอยู่แล้ว
    • ValidTo สำหรับเขตเลือกตั้งที่ไม่อัปเดตต้องเป็นวันก่อนการเลือกตั้ง

อัปเดตชื่อแทน

คุณใช้นามแฝงเพื่อทำเครื่องหมายรหัส OCD ว่าเป็นตัวแทนของภูมิศาสตร์การเมืองเดียวกันได้

  • ตัวอย่างเช่น หากสถานที่เป็นทั้งเมืองและเคาน์ตี ก็น่าจะเหมาะสม

หลักการทั่วไปที่เราพยายามผลักดัน:

  • หากภูมิศาสตร์ทางการเมือง 2 ส่วนมีคู่กัน ก็ไม่ควรใช้นามแฝงซึ่งกันและกัน เช่น การประชุมขนาดใหญ่ของรัฐในสหรัฐอเมริกาจะยึดตามรัฐต่างๆ แต่ก็เป็นไปตามความบังเอิญเนื่องจากจำนวนประชากรในสหรัฐอเมริกาในปัจจุบัน

นอกจากนี้ ชื่อแทนยังมีประโยชน์ในกรณีที่ต้องมีการเปลี่ยนแปลงที่สำคัญในกฎหมาย/การแก้ไขรัฐธรรมนูญเพื่อแยกเขตพื้นที่

  • เช่น วุฒิสภารัฐวอชิงตันและเขตสภาผู้แทนราษฎรถูกกำหนดให้เหมือนกันตามกฎหมายรัฐธรรมนูญ

หากจำเป็น ให้เพิ่มไฟล์ CSV aliases.csv ซึ่งเราเพิ่มทั้งรหัส OCD เก่าและชื่อแทน รหัส Canonical สามารถใช้ประเภทการหารที่มีความหมายภายในเครื่องและมีชื่อแทนที่มีตัวแทนที่คุ้นเคยมากขึ้นได้ (เช่น Canonical: ชื่อแทน ocd-division/country:de/land: `ocd-division/country:de/state) ดูปัญหา #170 สำหรับข้อมูลเพิ่มเติม

หากต้องการอัปเดตไฟล์Alias.csv ให้ทำดังนี้

  • จัดเรียงตามลำดับของคอลัมน์ในไฟล์Alias.csv: id,sameAs,sameAsNote
Type คำอธิบาย
id คอลัมน์นี้ต้องมีชื่อแทนของรหัส OCD
sameAs คอลัมน์นี้ต้องมีรหัส OCD จริงที่เราเพิ่มชื่อแทน
sameAsNote หมายเหตุที่อธิบายวิธีและสาเหตุที่การหารดังกล่าวมีตัวระบุหลายตัว

เช่น identifiers/country-in/aliases.csv

เรียกใช้สคริปต์ - compile.py

เรียกใช้สคริปต์ Python ที่ตำแหน่ง opencivicdata/ocd-division-ids/scripts ดังนี้

  • คุณต้องระบุรหัสประเทศ 2 ตัวอักษรเป็นอาร์กิวเมนต์ของสคริปต์เพื่อให้สคริปต์ทราบว่าต้องอัปเดตตัวระบุประเทศใด
  • ตัวอย่างเช่น: python3 Script/commerce คอมไพล์ใน (สำหรับการอัปเดต OCD ID ของเขตเลือกตั้งในอินเดีย)
  • ระบบไม่รองรับ Python 2.x ต้องใช้ Python 3 ขึ้นไป ดาวน์โหลด Python 3 เวอร์ชันล่าสุดได้ที่นี่

สคริปต์จะใช้ข้อมูลจากไฟล์ CSV ที่อัปเดตในขั้นตอนก่อนหน้า (ocd-division-ids/identifiers/country-in/*.csv) ตรวจสอบค่าในไฟล์ ตรวจสอบข้อผิดพลาดของข้อมูล (การใช้สัญลักษณ์พิเศษ ฯลฯ) หรือการทำซ้ำข้อมูล และเขียนรหัส OCD ใหม่ลงในไฟล์ CSV ของประเทศระดับบนสุด

สคริปต์จะแสดงข้อความแสดงข้อผิดพลาดและคำเตือนหากเกิดปัญหาในไฟล์ CSV ที่อัปเดตแล้ว แก้ไขปัญหาแล้วเรียกใช้สคริปต์อีกครั้ง

เพิ่มไฟล์ Readme

เมื่อคุณเพิ่มประเทศใหม่หรือการครอบคลุมระดับใหม่ (เช่น ก่อนหน้านี้เรามีเฉพาะรหัส OCD สำหรับประเทศนั้น แต่ตอนนี้กำลังเพิ่มเขตการปกครองระดับแรก) ให้เพิ่มหรืออัปเดตไฟล์ README.md ไฟล์นี้ต้องมีเค้าโครงคร่าวๆ ของภูมิศาสตร์ทางการเมือง ซึ่งรวมถึงข้อมูลต่อไปนี้

  • ประเภทที่เราจะใช้และบทบาท (เช่น "districts เป็นเขตบริหารระดับแรกของประเทศนี้")
  • ความสัมพันธ์ระหว่างประเภทต่างๆ (เช่น "เขตนิติบัญญัติได้รับการกำหนดแบบต่อเขตการศึกษา และไม่ข้ามขอบเขตของเขต")
  • ข้อยกเว้นที่เห็นได้ชัด (เช่น "มีเขตนิติบัญญัติ 1 เขตที่ครอบคลุมประชาชนในต่างประเทศ") และ
  • ลิงก์ไปยังหน้า Wikipedia ที่เป็นประโยชน์เพื่อให้บริบทแก่ผู้รีวิวหรือผู้ใช้

สร้างคำขอพุล

หากต้องการสร้างคำขอพุล ให้ใช้คำแนะนำต่อไปนี้

  • เมื่อขั้นตอนนี้เสร็จสมบูรณ์โดยไม่มีข้อผิดพลาด ให้ตรวจสอบไฟล์ .csv ของรหัสประเทศที่เขียนใหม่เป็นตัวอักษร "<2 ตัวอักษร>" ว่าตอนนี้มีรหัส OCD ชุดใหม่/ที่อัปเดตแล้ว
  • สร้างการดึงข้อมูลคำขอและเพิ่มผู้ตรวจสอบ คำขอพุลนี้ต้องรวมการแก้ไขที่ทำในไฟล์ CSV ต่อไปนี้ทั้งหมด
  • ไฟล์ CSV ในไดเรกทอรีของประเทศหนึ่งๆ ตัวอย่าง
  • ไฟล์รหัสประเทศระดับบนสุด <2 ตัวอักษร>.csv ตัวอย่าง
  • เมื่อคำขอพุลได้รับการตรวจสอบและอนุมัติโดยคณะกรรมการของประเทศ 2 ราย เจ้าของ/ผู้ทำงานร่วมกันคนใดคนหนึ่งของแพ็กเกจจะผสานรวมคำขอนั้น