From 1fffd9d832f15f9e138818fdd2b90458b8f47fdf Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Tue, 12 May 2026 15:50:05 -0700 Subject: [PATCH] =?UTF-8?q?docs(country-map):=20SIP=20=E2=80=94=20add=20pr?= =?UTF-8?q?ocedural/=20escape=20hatch=20for=20edge=20cases?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most touchups fit declarative YAML cleanly (typos, ISO codes, repositions, dissolves, composites). A few don't — e.g., the France-with-Overseas notebook drops a specific sub-polygon by index to avoid visual conflict with Corsica. Add a `procedural/` directory of small, named, single-purpose Python scripts as an escape hatch. Build orchestrator runs YAML transforms first, then iterates procedural/*.py in numeric order. Why this is much better than the notebook for the same content: - Each fix is a separate file → conflicts localize to one fix at a time, not "the whole notebook touched the same cell" - No kernel state, no output churn, pure functions on data - Naming forces documentation; reviewers see add/remove at a glance - Bounded growth: a 50-file procedural/ dir is annoying enough to signal "push back into YAML or upstream"; the notebook had no such signal and just bloated Co-Authored-By: Claude Opus 4.7 --- .../plugin-chart-country-map/SIP_DRAFT.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/superset-frontend/plugins/plugin-chart-country-map/SIP_DRAFT.md b/superset-frontend/plugins/plugin-chart-country-map/SIP_DRAFT.md index 6721b998242..dc71eb03e27 100644 --- a/superset-frontend/plugins/plugin-chart-country-map/SIP_DRAFT.md +++ b/superset-frontend/plugins/plugin-chart-country-map/SIP_DRAFT.md @@ -371,6 +371,40 @@ Ran a per-fix check against `ne_10m_admin_1_states_provinces.shp` (current). Fin - **Russia Chukchi antimeridian fix is likely obsolete.** NE has split Chukchi into properly-bounded polygons. We need to verify the new plugin's D3 projection handles them correctly at render time, but the data is in good shape. - **Net design surface shrinks:** the 6 NEW config files I sketched in the audit collapse to **4 NEW** (`territory_assignments`, `regional_aggregations`, `composite_maps`, plus the existing `name_overrides`/`flying_islands`/`iso_overrides`). One less config file, one less ongoing maintenance burden, no third-party data dependencies in-tree. +### Procedural escape hatch for edge cases + +Most touchups fit cleanly in declarative YAML (typos, ISO codes, repositions, dissolves, composites). A few don't — e.g., the France-with-Overseas notebook drops the *second sub-polygon* of the Windward Islands feature by array index to avoid visual conflict with Corsica. Forcing every such case into the YAML schema would bloat it. + +**Solution: small `procedural/` directory of named, single-purpose Python scripts** as an escape hatch, run by the build orchestrator after the YAML transforms. + +``` +scripts/country-maps/ + build.sh # orchestrator + config/ # declarative — handles 95% + name_overrides.yaml + flying_islands.yaml + territory_assignments.yaml + regional_aggregations.yaml + composite_maps.yaml + procedural/ # escape hatch — handles the rare 5% + README.md # when to use, when not + 01_fix_windward_islands_geometry.py + # ... future numbered one-offs +``` + +Each procedural script is: +- Single-purpose, named after what it does +- Has a header comment explaining *why* this couldn't be expressed in YAML +- Takes a geo input path, mutates, writes — clear in/out interface +- Numbered prefix for deterministic execution order +- Easily reviewable in PR (one fix per file, no kernel state, no cell ordering) + +Why this is much better than the notebook: +- Each fix is a separate file → conflicts localize to one fix at a time +- No kernel state, no output churn, pure functions on data +- Naming forces documentation; reviewers can see what's added/removed at a glance +- Bounded growth: a `procedural/` directory with 50 files is annoying enough to be a signal to push fixes back into YAML or upstream into NE. The notebook never had this signal — it just bloated. + ### What still requires manual attention going forward The fixes that survive (France typos/ISO codes, Philippines admin renames, China+SARs, Finland+Åland, regional aggregations, composite maps, flying islands) are all relatively **stable** — they don't change year over year. Once ported to YAML, the maintenance cost is roughly: "watch for new disputed-region PRs (handle via worldview switch) + occasional admin-name updates (one-line YAML edit)". Way better than the notebook treadmill.