更新 OCD ID 的流程

简介

开放公民数据标识符 (OCD ID) 是一种用于定义政治地理位置的通用标识符格式。如需创建 CDF Feed，您需要提供这些标识符作为 GpUnit 实体的一部分。本文档旨在提供将 OCD ID 添加到 opencivicdata GitHub 代码库的指导和最佳做法。

如何更新 Open Civic Data GitHub 代码库中的 OCD ID

前提条件

  1. 了解如何为开源项目做贡献

开始前须知：

  1. 准备工作站：

    从 OCD ID 代码库中复刻并克隆该软件包。

  2. 熟悉代码库：

    在 OCD ID 代码库中，每个受支持的国家/地区都由一个目录和一个同名的 CSV 文件表示：country-<2 个字母的国家/地区代码>（例如：identifiers/country-de 和 identifiers/country-de.csv 表示德国）。

    在要修改的国家/地区的目录中，您可以找到 CSV 文件（示例），其中包含特定国家/地区的顶级 CSV 文件的一部分。这些是您需要修改的文件。

  3. 如何创建新的 OCD ID：

    结构和源代码

    查看开放式公民数据文档，熟悉 OCD ID 结构。通常，有效的 OCD ID 采用以下格式：ocd-division/country:<country_code>(/<type>:<type_id>)

    如果 ISO 不可用，标识符命名会优先使用来自 ISO 的标准标识符或其他标准（如 FIPS 和 NUTS）。

    常规政策

    以下是一般性政策：

    层次结构

    OCD ID 层次结构必须由控制 OCD ID 边界的管理级别决定，而不一定是 OCD ID 包含关系。

    • 示例：在美国，国会选区用于国家众议院的选举，但其边界由各州决定。国会选区会在以下各州间挂钩：ocd-division/country:us/state:pa/cd:2
    • 示例：墨里斯维尔是宾夕法尼亚州的一个自治市，位于威斯特摩兰县。不过，城镇由国家管理，因此 OCD ID 悬挂在州之外： ocd-division/country:us/state:pa/place:murrysville 在需要消除歧义的情况下，可能会使用额外的层次结构。
    • 示例：宾夕法尼亚州有 16 个名为“富兰克林镇”的地点。通常，它们各自都有 OCD ID ocd-division/country:us/state:pa/place:franklin，但这并不明确。因此，我们可以将郡/县添加到 OCD ID 中，让每个国家/地区都有自己唯一的 OCD ID。 例如：ocd-division/country:us/state:pa/county:adams/place:franklin
    类型

    • OCD ID 类型通常因国家/地区而异。

    • 某些 OCD ID 在整个代码库中是通用的，例如 country、region 和 place。

    • 但是，按照一般准则，应尽量以更具体的方式指定类型，这种做法适用于该国家/地区。

      • 示例：对于美国行政区 1，会使用 state、district 和 territory 类型。
      • 示例：对于加利福尼亚州的行政区 1，会使用 province 和 territory 类型。
      • 示例：对于太平洋时间 (PT) 中的行政区 1，使用的是 region 和 autonomous_region 类型。
    ID
    • 一般来说，我们希望为选区的重新区划使用相同的 OCD ID。在选择用于一组新的 OCD ID 的 type_id 时，请选择一个最稳定的 ID。确定要使用哪个标识符时需要询问的一些问题包括：
    • 给定选区的标识符因选区重划而发生变化的可能性有多大？
    • 如果同一位官员在行政区划定区之前和之后担任第 X 区，我是否会将他们的任职期指定为连续任期？
    • 不同行政区划边界或名称相同的地区是否以相同的标识符表示？
      • 示例：在美国，美国国会选区的选区号会随着选区的重新划分而发生变化，尽管其边界会随着选区的重新划分而发生变化，但身份与区号密切相关，即便该区号跨越了新选区的边界，您也应该称其为第 N 个选区的任职者 X 年。
      • 示例：在加拿大，我们希望使用选区名称来表示联邦选举区，因为虽然存在联邦选举代码，但此标识符并不稳定，因为各选区中相同的选区以不同的 ID 表示。（例如，2012 年之前的区 47012 与之后的区划不同）。
    选区重划

    通常，在因区域重新划分而更新 OCD ID 时，请使用存在的 OCD ID 集，而不是创建新的 OCD ID。

    • 如果选区的身份（数字 ID、名称等）在重新区划后保持不变，请使用相同的 OCD ID。
    • 如需在重新划定区后创建新的学区，请创建新的 OCD ID。
    • 对于已不存在的选区，请更新 ValidThrough 字段，指定重新划分范围生效的日期。
    • 如果区的 ID 基于其名称，并且在重新划定区后重命名，请根据新的地区名称创建一个新 ID，并添加别名 id = oldId 和 sameAs = newId。这会将 newId 规范化，因为 oldId 的使用会映射到 newId。
    • 如果历史 OCD ID 之间存在冲突（例如新 ID 与已停用的 ID 完全相同），请将 ValidFrom 年附加到新 ID。如需详细了解此命名政策，请参阅为当前、已废除和已重命名的 OCD-ID 创建新文件。

更新本地副本

任何更新都需要在特定于国家/地区的目录下完成：ocd-repo/identifiers/country-<2 个字母的国家/地区代码>。如果不存在，请创建一个。

  • 如果 OCD ID CSV 文件已存在，并且代表旧的选举边界，则您需要更新此文件以包含新的选区。为此，请添加 ValidFrom 和 ValidTo 列，其中要包含 YYYY-MM-DD 格式的日期。
    • ValidFrom 应为新选票的选举日期。对于已存在选区，可以将其留空。
    • 对于过时的选民，ValidTo 必须是选举前一天。

更新别名

别名可用于将 OCD ID 标记为同一部分政治地理位置的表示形式。

  • 例如，如果某个地点既是城镇也是县/郡，那么这种配置就很合理。

我们尝试推行的一般原则：

  • 如果两个政治地理位置是相交的，则它们不应该彼此混淆。例如：大多数美国国会与州是共识的，但这是偶然性的，受当前美国人口数量的影响。

在需要对法律/宪法修正案进行重大更改来拆分选区时，别名也很合理。

  • 例如，根据宪法规定，华盛顿州参议院和州议会选区相同。

如果需要，请添加一个 CSV 文件 aliases.csv，我们会在该文件中添加旧的 OCD ID 及其别名。规范 ID 可以使用具有局部含义的除法类型，并且可以具有具有更熟悉的表示法的别名（例如，规范的 ocd-division/country:de/land 别名“ocd-division/country:de/state”）。如需了解详情，请参阅问题 170。

如需更新 alias.csv 文件，请执行以下操作：

  • 遵循 alias.csv 文件中各列的顺序：id、sameAs、sameAsNote
类型 说明
ID [id] 此列必须具有 OCD ID 的别名。
sameAs 此列必须包含我们会为其添加别名的实际 OCD ID。
sameAsNote 说明部门如何或为何使用多个标识符的备注。

示例：identifiers/country-in/aliases.csv

运行脚本 - compile.py

在 opencivicdata/ocd-division-ids/scripts 位置运行 Python 脚本：

  • 您必须指定由 2 个字母组成的国家/地区代码作为脚本的参数，以便脚本知道哪个国家/地区的标识符需要更新。
  • 示例：python3 scripts/compile.py in（用于更新印度选民的 OCD ID）。
  • Python 2.x 未获得支持。必须使用 Python 3 或更高版本。您可以点击此处下载最新版本的 Python 3。

该脚本从上一步中更新的 CSV 文件 (ocd-division-ids/identifiers/country-in/*.csv) 中获取数据，验证文件中的值，检查是否存在任何数据错误（使用特殊字符等）或数据重复，并将新的 OCD ID 写入顶级国家/地区 CSV 文件。

如果更新后的 CSV 文件中出现任何问题，脚本会抛出错误和警告消息。请先解决问题，然后再次运行脚本。

添加自述文件

在添加新的国家/地区或新的覆盖范围时（例如，我们之前只有相应国家/地区的 OCD ID，但现在添加了第一级行政区），请添加或更新 README.md 文件。此文件必须包含政治地理位置的简要概览，其中包括：

  • 我们将使用的类型及其角色（例如“districts 是此国家/地区的第一级行政区”）；
  • 各种类型之间的关系（例如“立法区是按区分配的，不会跨区边界进行分配”）；
  • 任何明显的例外情况（例如，“有一个立法选区涵盖所有海外公民”）；以及
  • 指向任何实用维基百科页面的链接，帮助为审核者或用户提供背景信息。

创建拉取请求

如需创建拉取请求，请使用以下指南：

  • 一旦此过程顺利完成，未出现任何错误，请检查新写入的顶级国家/地区代码 <2 个字母的国家/地区代码>.csv 文件，确保它现在包含一组已更新/新的 OCD ID。
  • 创建拉取请求并添加审核者。此拉取请求必须包含在以下所有 CSV 文件中进行的修改。
  • 特定国家/地区的目录中的 CSV 文件。示例
  • 顶级国家/地区 <2 个字母的国家/地区代码>.csv 文件。示例
  • 当拉取请求由一个国家/地区的两个提交者审核并批准时，软件包的其中一个所有者/协作者会合并该请求。