dr5hn · dr5hn · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -58,14 +58,15 @@ Agent rules — do this
 - If you change schema or fields, run the appropriate sync/import script and validate locally before committing.
 - When adding export features, follow the `bin/Commands/Export*.php` pattern (one command per output format).
 - **ALWAYS document fixes and PRs** in `.github/fixes-docs/`:
-  - Create a summary file (e.g., `FIX_<issue_number>_SUMMARY.md`) with:
+  - Create **only ONE markdown file per Issue/PR** (e.g., `FIX_<issue_number>_SUMMARY.md` or `<TOPIC>_SUMMARY.md`)
+  - The single file should contain:
     - Issue reference and executive summary
     - Countries/entities addressed
     - Changes made (before/after counts, examples)
     - Validation steps and results
-  - Create detailed documentation files for significant changes
-  - Include code examples, data samples, and validation commands
+    - Code examples, data samples, and validation commands
   - Follow existing format in `.github/fixes-docs/` directory
+  - Do NOT create multiple separate files for the same issue/PR
 
 Agent rules — do NOT do this
 - Do NOT commit generated export files (`json/`, `csv/`, `yml/`, `xml/`, `sqlite/`, `duckdb/`, `mongodb/`, `sqlite/`, `sqlserver/`, `psql/` dumps).

diff --git a/.github/fixes-docs/ETHIOPIA_CITIES_REASSIGNMENT.md b/.github/fixes-docs/ETHIOPIA_CITIES_REASSIGNMENT.md
@@ -0,0 +1,235 @@
+# Ethiopia Cities Reassignment to New States
+
+## Issue Reference
+- **Issue**: #1152 - Ethiopia state missing (Follow-up: City reassignment)
+- **Previous Fix**: Added Sidama (SI) and Southwest Ethiopia Peoples (SW) states
+- **Date**: 2025-10-14
+
+## Executive Summary
+Reassigned 12 cities from Southern Nations, Nationalities and Peoples Region (SN) to the newly created Sidama (SI) and Southwest Ethiopia Peoples (SW) regions, completing the administrative restructuring of Ethiopia that began in 2020-2021.
+
+## Background
+In the previous fix (documented in `FIX_ETHIOPIA_MISSING_STATES.md`), we added two new regional states to Ethiopia:
+1. **Sidama** (ET-SI) - Formed in 2020
+2. **Southwest Ethiopia Peoples** (ET-SW) - Formed in 2021
+
+Both were separated from the Southern Nations, Nationalities and Peoples Region (SNNPR). This PR completes that work by reassigning the appropriate cities to their correct states.
+
+## Changes Made
+
+### Cities Reassigned to Sidama (SI, state_id: 5465)
+
+| ID | City Name | Coordinates | Notes |
+|----|-----------|-------------|-------|
+| 38651 | Hawassa | 7.06°N, 38.48°E | **Capital of Sidama** |
+| 38625 | Dīla | 6.42°N, 38.32°E | Major city |
+| 38655 | Hāgere Selam | 6.48°N, 38.52°E | Town |
+| 38719 | Yirga 'Alem | 6.75°N, 38.42°E | Town |
+| 38710 | Wendo | 6.60°N, 38.42°E | Town |
+| 38672 | Leku | 6.87°N, 38.44°E | Town |
+| 38698 | Sidama Zone | 6.72°N, 38.45°E | Administrative zone |
+
+**Total: 7 cities**
+
+### Cities Reassigned to Southwest Ethiopia Peoples (SW, state_id: 5466)
+
+| ID | City Name | Coordinates | Notes |
+|----|-----------|-------------|-------|
+| 38607 | Bonga | 7.28°N, 36.23°E | **Capital of Southwest** |
+| 38683 | Mīzan Teferī | 6.99°N, 35.59°E | Major city |
+| 38705 | Tippi | 7.20°N, 35.45°E | Town |
+| 38603 | Bench Maji Zone | 6.46°N, 35.31°E | Administrative zone |
+| 38696 | Sheka Zone | 7.56°N, 35.40°E | Administrative zone |
+
+**Total: 5 cities**
+
+## City Distribution Changes
+
+### Before
+```
+SN (Southern Nations): 33 cities
+SI (Sidama): 0 cities
+SW (Southwest): 0 cities
+```
+
+### After
+```
+SN (Southern Nations): 21 cities (-12)
+SI (Sidama): 7 cities (+7)
+SW (Southwest): 5 cities (+5)
+```
+
+### Complete Ethiopia Distribution (All 13 States)
+
+| State Code | State Name | Cities |
+|------------|------------|--------|
+| AA | Addis Ababa | 1 |
+| AF | Afar | 7 |
+| AM | Amhara | 29 |
+| BE | Benishangul-Gumuz | 2 |
+| DD | Dire Dawa | 1 |
+| GA | Gambela Peoples | 2 |
+| HA | Harari People | 1 |
+| OR | Oromia | 54 |
+| **SI** | **Sidama** | **7** ✨ |
+| SN | Southern Nations... | 21 |
+| SO | Somali | 6 |
+| **SW** | **Southwest Ethiopia Peoples** | **5** ✨ |
+| TI | Tigrai | 8 |
+| **TOTAL** | **13 states** | **144 cities** |
+
+## Validation
+
+### City Count Verification
+```bash
+# Total cities (should remain 144)
+jq 'length' contributions/cities/ET.json
+# Output: 144 ✅
+
+# Sidama cities
+jq '[.[] | select(.state_code == "SI")] | length' contributions/cities/ET.json
+# Output: 7 ✅
+
+# Southwest cities
+jq '[.[] | select(.state_code == "SW")] | length' contributions/cities/ET.json
+# Output: 5 ✅
+
+# Southern Nations cities (reduced)
+jq '[.[] | select(.state_code == "SN")] | length' contributions/cities/ET.json
+# Output: 21 ✅
+```
+
+### State ID Verification
+```bash
+# Verify Sidama cities have correct state_id
+jq '[.[] | select(.state_code == "SI")] | .[0].state_id' contributions/cities/ET.json
+# Output: 5465 ✅
+
+# Verify Southwest cities have correct state_id
+jq '[.[] | select(.state_code == "SW")] | .[0].state_id' contributions/cities/ET.json
+# Output: 5466 ✅
+```
+
+### JSON Validation
+```bash
+python3 -m json.tool contributions/cities/ET.json > /dev/null
+# Output: (no errors) ✅
+```
+
+## Implementation Details
+
+### Approach
+Used a Python script to update the cities programmatically:
+1. Identified 12 cities based on geographic coordinates and historical references
+2. Updated `state_id` field to correct values (5465 for SI, 5466 for SW)
+3. Updated `state_code` field to correct values ('SI' or 'SW')
+4. Maintained all other fields unchanged (timestamps, translations, etc.)
+
+### Files Modified
+- `contributions/cities/ET.json` (12 city records updated)
+
+### Selection Criteria
+Cities were selected based on:
+1. Geographic coordinates matching the regions
+2. Historical administrative assignments
+3. Wikipedia and ISO 3166-2:ET sources
+4. Capital cities of each new region
+
+### Data Sources
+- Previous fix documentation: `.github/fixes-docs/FIX_ETHIOPIA_MISSING_STATES.md`
+- Wikipedia - Sidama Region: https://en.wikipedia.org/wiki/Sidama_Region
+- Wikipedia - Southwest Ethiopia Peoples Region: https://en.wikipedia.org/wiki/South_West_Ethiopia_Peoples%27_Region
+- ISO 3166-2:ET: https://www.iso.org/obp/ui#iso:code:3166:ET
+
+## Examples
+
+### Before: Hawassa (Capital of Sidama)
+```json
+{
+  "id": 38651,
+  "name": "Hawassa",
+  "state_id": 1,          ← Was assigned to SN
+  "state_code": "SN",     ← Was SN
+  "country_code": "ET",
+  ...
+}
+```
+
+### After: Hawassa (Capital of Sidama)
+```json
+{
+  "id": 38651,
+  "name": "Hawassa",
+  "state_id": 5465,       ← Now assigned to SI
+  "state_code": "SI",     ← Now SI
+  "country_code": "ET",
+  ...
+}
+```
+
+### Before: Bonga (Capital of Southwest)
+```json
+{
+  "id": 38607,
+  "name": "Bonga",
+  "state_id": 1,          ← Was assigned to SN
+  "state_code": "SN",     ← Was SN
+  "country_code": "ET",
+  ...
+}
+```
+
+### After: Bonga (Capital of Southwest)
+```json
+{
+  "id": 38607,
+  "name": "Bonga",
+  "state_id": 5466,       ← Now assigned to SW
+  "state_code": "SW",     ← Now SW
+  "country_code": "ET",
+  ...
+}
+```
+
+## Testing
+
+### Automated Validation
+- ✅ JSON syntax is valid
+- ✅ Total city count unchanged (144)
+- ✅ All 12 cities successfully reassigned
+- ✅ State IDs correctly set (5465 for SI, 5466 for SW)
+- ✅ State codes correctly set ('SI' and 'SW')
+- ✅ No duplicate city assignments
+- ✅ All other fields preserved
+
+### Manual Verification
+- ✅ Hawassa correctly assigned as capital of Sidama
+- ✅ Bonga correctly assigned as capital of Southwest
+- ✅ Geographic coordinates align with new regions
+- ✅ Southern Nations count reduced appropriately
+
+## Impact
+
+### Coverage
+- All 13 Ethiopian states now have cities assigned
+- 100% of Ethiopia's administrative divisions covered
+- Complete ISO 3166-2:ET compliance
+
+### Data Quality
+- Improved geographic accuracy
+- Correct administrative assignments
+- Up-to-date with 2020-2021 regional changes
+
+## Future Work
+1. ✅ **COMPLETED**: Add missing Sidama and Southwest states
+2. ✅ **COMPLETED**: Reassign cities to new states
+3. 🔄 **Optional**: Add more cities to SI and SW regions if available
+4. 🔄 **Optional**: Verify remaining SN cities are correctly assigned
+
+## Conclusion
+Ethiopia's city data is now fully aligned with the current administrative structure. All 144 cities are correctly assigned to their respective states, including the newly created Sidama and Southwest Ethiopia Peoples regions.
+
+## References
+- Issue: #1152
+- Previous documentation: `.github/fixes-docs/FIX_ETHIOPIA_MISSING_STATES.md`
+- Previous summary: `.github/fixes-docs/ETHIOPIA_SUMMARY.md`
diff --git a/.github/fixes-docs/ETHIOPIA_SUMMARY.md b/.github/fixes-docs/ETHIOPIA_SUMMARY.md
@@ -20,19 +20,31 @@
 
 ## Before vs After
 
-| Metric | Before | After |
-|--------|--------|-------|
-| Ethiopian States | 11 | **13** ✅ |
-| Regional States | 9 | **11** ✅ |
-| Administrations | 2 | 2 |
-| ISO Compliance | ❌ | ✅ |
+| Metric | Before | After | Now |
+|--------|--------|-------|-----|
+| Ethiopian States | 11 | **13** ✅ | **13** ✅ |
+| Regional States | 9 | **11** ✅ | **11** ✅ |
+| Administrations | 2 | 2 | 2 |
+| ISO Compliance | ❌ | ✅ | ✅ |
+| Cities in SI | 0 | 0 | **7** ✅ |
+| Cities in SW | 0 | 0 | **5** ✅ |
+| Cities in SN | 33 | 33 | **21** ✅ |
+| States with Cities | 11 | 11 | **13** ✅ |
 
 ## Files Changed
 - `contributions/states/states.json` (added 2 entries)
+- `contributions/cities/ET.json` (reassigned 12 cities)
+
+## City Reassignment (Completed)
+✅ **Completed**: 2025-10-14  
+- Reassigned 12 cities from SNNPR to new regions
+- 7 cities → Sidama (SI)
+- 5 cities → Southwest Ethiopia Peoples (SW)
+- See: `.github/fixes-docs/ETHIOPIA_CITIES_REASSIGNMENT.md`
 
 ## Next Steps (Future PRs)
-1. Reassign ~12 cities from SNNPR to new regions once state IDs are assigned
-2. Add additional cities for new regions if needed
+1. ✅ ~~Reassign ~12 cities from SNNPR to new regions~~ **COMPLETED**
+2. 🔄 Add additional cities for new regions if available
 
 ## References
 - ISO 3166-2:ET: https://www.iso.org/obp/ui#iso:code:3166:ET