From 3f35a428774bbcfbffd739adc795f9c2e75e9e3a Mon Sep 17 00:00:00 2001 From: ericgodwin Date: Mon, 10 Aug 2026 12:34:43 -0700 Subject: [PATCH 1/4] chore: add Overture issue template and field sync workflow Adds .github/ISSUE_TEMPLATE/overture.yaml (Type, Scope, Skillset, Description), config.yml disabling blank issues, and the sync-issue-type-and-scope workflow that populates the org-level fields from the form answers. Closes #473 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: ericgodwin --- .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/overture.yaml | 49 +++++++++++++++++++ .../workflows/sync-issue-type-and-scope.yml | 25 ++++++++++ 3 files changed, 75 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/overture.yaml create mode 100644 .github/workflows/sync-issue-type-and-scope.yml diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/overture.yaml b/.github/ISSUE_TEMPLATE/overture.yaml new file mode 100644 index 00000000..794881ef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/overture.yaml @@ -0,0 +1,49 @@ +name: Overture +description: General issue for work tracked in the Overture project. +projects: ["OvertureMaps/84"] +body: + - type: dropdown + id: type + attributes: + label: Type + description: What kind of work is this? Used to populate the organization-level `Type` field during triage. + options: + - Task + - Bug + - Agenda + validations: + required: true + - type: dropdown + id: scope + attributes: + label: Scope + description: Primary theme or platform impacted. Used to populate the organization-level `Scope` field during triage. + options: + - Addresses + - Base + - Buildings + - Divisions + - Places + - Transportation + - Multi-theme or Platform + validations: + required: true + - type: dropdown + id: skillset + attributes: + label: Skillset + description: Primary skill needed to complete this task. Used to populate the organization-level `Skillset` field during triage. + options: + - data analysis + - data science + - dev ops + - engineering + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + placeholder: Describe what this issue is trying to accomplish (what), context (why), constraints, acceptance criteria, design details (how), and testing + validations: + required: true diff --git a/.github/workflows/sync-issue-type-and-scope.yml b/.github/workflows/sync-issue-type-and-scope.yml new file mode 100644 index 00000000..e3108e14 --- /dev/null +++ b/.github/workflows/sync-issue-type-and-scope.yml @@ -0,0 +1,25 @@ +--- +name: Sync issue Type and Scope + +on: + issues: + types: [opened] + +# One sync run per issue at a time; drop duplicate triggers. +concurrency: + group: sync-issue-type-scope-${{ github.event.issue.number }} + cancel-in-progress: true + +permissions: {} + +jobs: + sync-fields: + name: Sync Fields + runs-on: ubuntu-slim + permissions: + issues: write # for the sync action to set org-level Type, Scope, and Skillset + steps: + - name: Sync Type and Scope from form answers + uses: OvertureMaps/workflows/.github/actions/sync-issue-fields@main # zizmor: ignore[unpinned-uses] intentionally track main + with: + github-token: ${{ secrets.GITHUB_TOKEN }} From a5bd13f04b9d8348fcd46fc8555819945a20099e Mon Sep 17 00:00:00 2001 From: ericgodwin Date: Tue, 11 Aug 2026 14:56:37 -0700 Subject: [PATCH 2/4] chore: make Skillset optional in the Overture issue template Skillset is often not known at issue-open time; leave it to triage rather than blocking submission. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: ericgodwin --- .github/ISSUE_TEMPLATE/overture.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/overture.yaml b/.github/ISSUE_TEMPLATE/overture.yaml index 794881ef..f7f8337e 100644 --- a/.github/ISSUE_TEMPLATE/overture.yaml +++ b/.github/ISSUE_TEMPLATE/overture.yaml @@ -38,8 +38,6 @@ body: - data science - dev ops - engineering - validations: - required: true - type: textarea id: description attributes: From 13b668c9caa48ff2f96d54449690b967d2262905 Mon Sep 17 00:00:00 2001 From: ericgodwin Date: Wed, 12 Aug 2026 08:56:09 -0700 Subject: [PATCH 3/4] chore: exclude generated schema reference docs from textlint docs/schema/reference/ is codegen output synced from OvertureMaps/schema. It is already excluded from markdownlint via .markdownlintignore, but had no textlint equivalent, so 9 terminology errors failed the Super-Linter NATURAL_LANGUAGE check on every branch. Fixing the text in place would regress on the next codegen sync, and several findings are false positives against generated content: the 'Id' heading in system/ref/id.md is a schema type name matching its sibling pages, and 'websites' in places/place.md refers to the schema field of that name. Add .textlintignore mirroring .markdownlintignore. textlint auto-discovers it from the working directory, so no change to lint.yml is needed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: ericgodwin --- .textlintignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .textlintignore diff --git a/.textlintignore b/.textlintignore new file mode 100644 index 00000000..5acac690 --- /dev/null +++ b/.textlintignore @@ -0,0 +1,2 @@ +# Generated by OvertureMaps/schema — do not lint +docs/schema/reference/**/* From 9d6e91aadea3c3e1a6918555f3816127dcee19e5 Mon Sep 17 00:00:00 2001 From: ericgodwin Date: Wed, 12 Aug 2026 12:26:04 -0700 Subject: [PATCH 4/4] chore: fix textlint terminology errors in schema reference docs Replaces the blanket .textlintignore added earlier with actual fixes. Fixed in place (8 of 9): - 'Key/value pairs' -> 'Key-value pairs' (5 files) - 'a snake case identifier' -> 'a `snake_case` identifier' (2 occurrences); backticks are correct here since it names an identifier, and the terminology rule skips inline code - 'The websites of the place.' -> 'The web addresses of the place.' The remaining error is the '# Id' heading in system/ref/id.md. Id is the literal name of the schema NewType, and the reference sidebar is autogenerated with no frontmatter, so Docusaurus derives the page title from that heading -- it cannot be reworded or backticked without changing the rendered navigation. Excluded the single 'ID' term instead; every other terminology term stays enforced repo-wide. These files are generated from OvertureMaps/schema, so the wording fixes need to be mirrored upstream (_common.py, string.py, place.yaml/place.py) or they will regress on the next codegen sync. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: ericgodwin --- .github/linters/.textlintrc.json | 2 +- .textlintignore | 2 -- docs/schema/reference/base/infrastructure.md | 2 +- docs/schema/reference/base/land.md | 2 +- docs/schema/reference/base/land_use.md | 2 +- docs/schema/reference/base/types/source_tags.md | 2 +- docs/schema/reference/base/water.md | 2 +- docs/schema/reference/places/place.md | 2 +- docs/schema/reference/system/snake_case_string.md | 4 ++-- 9 files changed, 9 insertions(+), 11 deletions(-) delete mode 100644 .textlintignore diff --git a/.github/linters/.textlintrc.json b/.github/linters/.textlintrc.json index 4ef3eab6..78998baf 100644 --- a/.github/linters/.textlintrc.json +++ b/.github/linters/.textlintrc.json @@ -4,7 +4,7 @@ }, "rules": { "terminology": { - "exclude": ["to-?do(s)?(?=[ ,.])"] + "exclude": ["to-?do(s)?(?=[ ,.])", "ID"] } } } diff --git a/.textlintignore b/.textlintignore deleted file mode 100644 index 5acac690..00000000 --- a/.textlintignore +++ /dev/null @@ -1,2 +0,0 @@ -# Generated by OvertureMaps/schema — do not lint -docs/schema/reference/**/* diff --git a/docs/schema/reference/base/infrastructure.md b/docs/schema/reference/base/infrastructure.md index 8f3432f8..f2526d26 100644 --- a/docs/schema/reference/base/infrastructure.md +++ b/docs/schema/reference/base/infrastructure.md @@ -45,7 +45,7 @@ such as bridges, airports, runways, aerialways, communication towers, and power | `names.rules[].between` | [`LinearlyReferencedRange`](../common/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. | | `names.rules[].side` | [`Side`](../common/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. | | `level` | [`Level`](../common/level.md) (optional) | Z-order of the feature where 0 is visual level | -| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key/value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | +| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | | `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ | ## Examples diff --git a/docs/schema/reference/base/land.md b/docs/schema/reference/base/land.md index b54eb24a..97062066 100644 --- a/docs/schema/reference/base/land.md +++ b/docs/schema/reference/base/land.md @@ -55,7 +55,7 @@ TODO: Update this description when the relationship to `land_cover` is better un | `names.rules[].between` | [`LinearlyReferencedRange`](../common/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. | | `names.rules[].side` | [`Side`](../common/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. | | `level` | [`Level`](../common/level.md) (optional) | Z-order of the feature where 0 is visual level | -| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key/value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | +| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | | `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ | ## Examples diff --git a/docs/schema/reference/base/land_use.md b/docs/schema/reference/base/land_use.md index 40b9d21b..cb8df33a 100644 --- a/docs/schema/reference/base/land_use.md +++ b/docs/schema/reference/base/land_use.md @@ -50,7 +50,7 @@ TODO: Explain relationship to `Land` features. | `names.rules[].between` | [`LinearlyReferencedRange`](../common/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. | | `names.rules[].side` | [`Side`](../common/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. | | `level` | [`Level`](../common/level.md) (optional) | Z-order of the feature where 0 is visual level | -| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key/value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | +| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | | `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ | ## Examples diff --git a/docs/schema/reference/base/types/source_tags.md b/docs/schema/reference/base/types/source_tags.md index 41f50ae8..aaac9760 100644 --- a/docs/schema/reference/base/types/source_tags.md +++ b/docs/schema/reference/base/types/source_tags.md @@ -1,6 +1,6 @@ # SourceTags -Key/value pairs imported directly from the source data without change. +Key-value pairs imported directly from the source data without change. This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. diff --git a/docs/schema/reference/base/water.md b/docs/schema/reference/base/water.md index 5b2bd143..e2bfb1f7 100644 --- a/docs/schema/reference/base/water.md +++ b/docs/schema/reference/base/water.md @@ -66,7 +66,7 @@ and `water=*`. | `names.rules[].perspectives.countries` | `list<`[`CountryCodeAlpha2`](../system/country_code_alpha2.md)`>` | Countries holding the given mode of perspective. | | `names.rules[].between` | [`LinearlyReferencedRange`](../common/scoping/linearly_referenced_range.md) (list, optional) | The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to. | | `names.rules[].side` | [`Side`](../common/scoping/side.md) (optional) | The side, either left or right, that the containing NameRule applies to. | -| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key/value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | +| `source_tags` | [`SourceTags`](types/source_tags.md) (map, optional) | Key-value pairs imported directly from the source data without change.

This field provides access to raw OSM entity tags for features sourced from OpenStreetMap. | | `wikidata` | [`WikidataId`](../system/wikidata_id.md) (optional) | A wikidata ID, as found on https://www.wikidata.org/ | ## Examples diff --git a/docs/schema/reference/places/place.md b/docs/schema/reference/places/place.md index 2b8b2bd6..d145a4da 100644 --- a/docs/schema/reference/places/place.md +++ b/docs/schema/reference/places/place.md @@ -37,7 +37,7 @@ Places are point representations of real-world facilities, businesses, services, | `taxonomy.hierarchy` | `list<`[`SnakeCaseString`](../system/snake_case_string.md)`>` | The full primary hierarchy of categories known for this place, ordered from most general to most specific. An example hierarchy might be: `["food_and_drink", "restaurant", "casual_eatery", "gas_station_sushi"]`.

The rightmost, or most specific, value in the `hierarchy` must always be equal to the `primary` field. The basic level category of the place will typically be found in the middle of the primary hierarchy. The primary hierarchy does not include any of the alternate categories found in the `alternates` field. | | `taxonomy.alternates` | `list<`[`SnakeCaseString`](../system/snake_case_string.md)`>` (optional) | Unordered list of additional categories that are known for this place but that are not part of the primary category hierarchy.

Alternate categories allow a more complete picture of the place to be surfaced when it fits multiple unconnected branches in the taxonomy. For example a gas station that also sells groceries might have primary category of "gas_station" with an alternate of "grocery_store".

Alternate categories are not part of the primary hierarchy or another alternate category's hierarchy. In other words, if a category is a parent in the hierarchy of another category, that category can't be a primary or alternate category itself.

Note as well that this field is an unordered list of extra categories and does not represent a hierarchy. | | `confidence` | [`ConfidenceScore`](../common/confidence_score.md) (optional) | A score between 0 and 1 indicating how confident we are that the place exists.

A confidence score of 0 indicates that we are certain the place doesn't exist anymore and will always be paired with an `operating_status` of `"permanently_closed"`.

A confidence score of 1 indicates that we are certain the place does exist.

If there is no value for confidence, it means we don't have enough information on which to estimate our confidence level. | -| `websites` | `list<`[`HttpUrl`](../pydantic/networks/http_url.md)`>` (optional) | The websites of the place.

*Minimum length: 1*
*All items must be unique. (`UniqueItemsConstraint`)* | +| `websites` | `list<`[`HttpUrl`](../pydantic/networks/http_url.md)`>` (optional) | The web addresses of the place.

*Minimum length: 1*
*All items must be unique. (`UniqueItemsConstraint`)* | | `socials` | `list<`[`HttpUrl`](../pydantic/networks/http_url.md)`>` (optional) | The social media URLs of the place.

*Minimum length: 1*
*All items must be unique. (`UniqueItemsConstraint`)* | | `emails` | `list<`[`EmailStr`](../pydantic/networks/email_str.md)`>` (optional) | The email addresses of the place.

*Minimum length: 1*
*All items must be unique. (`UniqueItemsConstraint`)* | | `phones` | `list<`[`PhoneNumber`](../system/phone_number.md)`>` (optional) | The phone numbers of the place.

*Minimum length: 1*
*All items must be unique. (`UniqueItemsConstraint`)* | diff --git a/docs/schema/reference/system/snake_case_string.md b/docs/schema/reference/system/snake_case_string.md index 4bfeb76e..6c8cd4c8 100644 --- a/docs/schema/reference/system/snake_case_string.md +++ b/docs/schema/reference/system/snake_case_string.md @@ -1,12 +1,12 @@ # SnakeCaseString -A string that looks like a snake case identifier, like a Python variable name (*e.g.*, `foo_bar`). +A string that looks like a `snake_case` identifier, like a Python variable name (*e.g.*, `foo_bar`). Underlying type: `string` ## Constraints -- Allows only strings that look like snake case identifiers, *e.g.* `"foo_bar"`. (`SnakeCaseConstraint`, pattern: `^[a-z0-9]+(_[a-z0-9]+)*$`) +- Allows only strings that look like `snake_case` identifiers, *e.g.* `"foo_bar"`. (`SnakeCaseConstraint`, pattern: `^[a-z0-9]+(_[a-z0-9]+)*$`) ## Used By