WeRelate MediaWiki Development
This skill provides guidance for working with the WeRelate.org codebase, a genealogical wiki built on MediaWiki with custom structured namespaces for Person, Family, Place, Source pages and specialized functionality for family tree visualization and GEDCOM import/export.
When to Use This Skill
Use this skill when working with:
WeRelate.org codebase modificationsMediaWiki extensions for genealogical dataStructured namespace implementationsFamily tree visualization featuresGEDCOM import/export functionalityGenealogical data management systemsProject Architecture Overview
WeRelate extends MediaWiki with:
**Custom structured namespaces** for genealogical data (Person, Family, Place, Source, etc.)**Family tree visualization** and analysis tools**GEDCOM import/export** for genealogy file interchange**External search service** integration**Data quality validation** system**Propagation system** for cascading edits across linked pagesDevelopment Instructions
1. Understanding the Codebase Structure
Before making changes, familiarize yourself with these key areas:
**Core MediaWiki Files:**
`index.php` - Main entry point`LocalSettings.php` - Site configuration (uses environment variables)`includes/` - MediaWiki core files**Custom Structured Namespaces** (`extensions/structuredNamespaces/`):
`StructuredData.php` - Base class for all structured namespaces`Person.php` - Individual person pages (NS_PERSON = 108)`Family.php` - Family pages linking spouses/children (NS_FAMILY = 110)`Place.php` - Geographic locations (NS_PLACE = 106)`Source.php` - Citations and sources (NS_SOURCE = 104)`Name.php` - Given names and surnames (NS_GIVEN_NAME = 100, NS_SURNAME = 102)`MySource.php` - User-specific sources (NS_MYSOURCE = 112)`Repository.php` - Archive information (NS_REPOSITORY = 114)`Transcript.php` - Historical documents (NS_TRANSCRIPT = 118)**Family Tree Features** (`extensions/familytree/`):
`FamilyTree.php` - Core tree data structure`SpecialShowFamilyTree.php` - Tree visualization`SpecialTreeRelated.php` - Find related people**GEDCOM Support** (`extensions/gedcom/`):
`SpecialGedcomPage.php` - Upload and processing`GedcomExportJob.php` - Background export jobs**Special Pages** (`extensions/other/`):
`SpecialSearch.php` - Custom search interface`SpecialMerge.php` - Merge duplicate pages`SpecialDataQuality.php` - Data quality reports2. Setting Up Development Environment
**Database Setup:**
```bash
wget http://public.werelate.org.s3.amazonaws.com/wikidb.sql
mysql -u [user] -p [database_name] < wikidb.sql
```
**Simple Configuration:**
```bash
cp htaccess.sample .htaccess
Edit environment variables in .htaccess
```
**Full Apache Setup:**
1. Copy files to `w/` directory under htdocs root
2. Create site file from `conf/apache2.sample`
3. Copy to `apache2/sites-available/[sitename]`
4. Modify values for your environment
5. Enable: `a2ensite [sitename]`
**Running Background Jobs:**
```bash
php maintenance/runJobs.php
```
Note: Jobs are disabled in web context (`$wgJobRunRate = 0`)
3. Working with Structured Namespaces
All structured namespaces extend `StructuredData.php` which provides:
XML parsing and validationEdit form renderingData import from formsEdit propagation across linked pagesData quality checking**Extension Loading Order Matters:**
Source and UserPage must load before Name and Place (they contain names/places).
**Structured Data XML Format:**
Pages embed XML within wiki markup:
```xml
<person>
<name>...</name>
<gender>...</gender>
<event_fact>...</event_fact>
</person>
```
**Key MediaWiki Hooks Used:**
`ArticleEditShow` - Render custom edit forms`ImportEditFormDataComplete` - Import form data`EditFilter` - Validate before saving`ArticleSave` - Propagate changes after save`TitleMoveComplete` - Handle page moves`ArticleDeleteComplete` - Handle deletions4. Understanding the Propagation System
When a Person/Family/Place page changes, updates cascade to linked pages:
1. Hook detects the change
2. `PropagationManager.php` identifies affected pages
3. Affected pages updated with `PROPAGATE_EDIT_FLAGS` (minor bot edit)
**Key File:** `extensions/structuredNamespaces/PropagationManager.php`
5. Working with Family Trees
**Core Files:**
`extensions/familytree/FamilyTree.php` - Data structure`extensions/familytree/FamilyTreePropagator.php` - Update logic`familytree.js` - Frontend visualization**Special Pages:**
`SpecialShowFamilyTree.php` - View family trees`SpecialTreeRelated.php` - Find relationships`SpecialCopyTree.php` - Copy tree branches`SpecialTreeDeletionImpact.php` - Analyze deletion impact6. GEDCOM Import/Export
**Upload Directory Structure:**
Configure in LocalSettings.php:
`$wrGedcomUploadDirectory` - Uploaded files`$wrGedcomInprocessDirectory` - Processing`$wrGedcomXMLDirectory` - Parsed XML`$wrGedcomExportDirectory` - Generated exports`$wrGedcomArchiveDirectory` - Archived files**Key Files:**
`extensions/gedcom/SpecialGedcomPage.php` - Upload interface`extensions/gedcom/GedcomExportJob.php` - Background export`extensions/gedcom/GedcomAjaxFunctions.php` - AJAX handlers7. Search Architecture
WeRelate uses an external search service (not MediaWiki's built-in search):
`$wgDisableTextSearch = true` disables MediaWiki search`SpecialSearch.php` queries external service via HTTPSearch service configured via `$wrSearchHost`, `$wrSearchPort`, `$wrSearchPath`Place search uses separate endpoint: `$wrPlaceSearchHost`, `$wrPlaceSearchPort`**Note:** The external search service is a separate project.
8. Data Quality System
**Key Files:**
`extensions/structuredNamespaces/DQHandler.php` - Validation logic`extensions/other/SpecialDataQuality.php` - Quality reports`extensions/other/SpecialDQStats.php` - Statistics**Validates:**
Missing datesInvalid placesBroken linksFormatting problems9. AJAX Functionality
**AJAX Dispatching:**
`includes/AjaxDispatcher.php` - Routes AJAX requests**AJAX Handlers:**
`extensions/other/IndexAjaxFunctions.php` - Index pages`extensions/other/ListAjaxFunctions.php` - List pages`extensions/familytree/FamilyTreeAjaxFunctions.php` - Family trees`extensions/gedcom/GedcomAjaxFunctions.php` - GEDCOM operations10. Custom Parser Tags
Registered in `extensions/other/Hooks.php`:
`<wr_img>` - Image embedding`<youtube>` - YouTube videos`<googlemap>` - Google Maps`<addsubpage>` / `<listsubpages>` - Subpage management`<person_count>` - Person statistics11. Testing and Debugging
**Manual Testing Required:**
1. Edit files
2. Clear cache if using memcached
3. Test in browser
**Debug Logging:**
`$wgDebugLogFile` - General debug log (configured in LocalSettings.php)`$wgRateLimitLog` - Rate limit violations12. Important Constraints
This is a modified MediaWiki installation (older version)Jobs must run via command line: `php maintenance/runJobs.php`Anonymous users cannot edit: `$wgGroupPermissions['*']['edit'] = false`Email confirmation required: `$wgEmailConfirmToEdit = true`Tidy HTML cleanup disabled: `$wgUseTidy = false`Rate limiting differs between night and day: `$wrNightBegin`, `$wrNightEnd`13. Related Projects
WeRelate is part of an ecosystem:
**search project** - Search indexing and query service**werelate-gedcom project** - GEDCOM parsing**gedcom-review project** - GEDCOM review interface**wikidata project** - Data parsing and batch update scriptsExample Workflow
Adding a New Structured Namespace
1. Create new class extending `StructuredData.php` in `extensions/structuredNamespaces/`
2. Define namespace constant in `LocalSettings.php` (even number)
3. Implement required methods: `validate()`, `renderEdit()`, `importData()`
4. Register MediaWiki hooks for save/move/delete propagation
5. Add to extension loading order in `LocalSettings.php`
6. Test edit form, validation, and propagation
Modifying Family Tree Visualization
1. Identify changes needed in `extensions/familytree/FamilyTree.php` (backend)
2. Update visualization logic in `familytree.js` (frontend)
3. If adding special page, extend `SpecialPage` in `extensions/familytree/`
4. Clear browser cache and test rendering
5. Test propagation when linked pages change
Debugging a GEDCOM Import Issue
1. Check uploaded file in `$wrGedcomUploadDirectory`
2. Review parsed XML in `$wrGedcomXMLDirectory`
3. Check `SpecialGedcomPage.php` for processing logic
4. Review `GedcomAjaxFunctions.php` for AJAX handlers
5. Check debug logs: `$wgDebugLogFile`
6. Run jobs manually: `php maintenance/runJobs.php`
Key Files Reference
| Purpose | File Path |
|---------|-----------|
| Entry point | `index.php` |
| Configuration | `LocalSettings.php` |
| Structured namespace base | `extensions/structuredNamespaces/StructuredData.php` |
| Person pages | `extensions/structuredNamespaces/Person.php` |
| Family pages | `extensions/structuredNamespaces/Family.php` |
| Place pages | `extensions/structuredNamespaces/Place.php` |
| Edit propagation | `extensions/structuredNamespaces/PropagationManager.php` |
| Data quality | `extensions/structuredNamespaces/DQHandler.php` |
| Family tree core | `extensions/familytree/FamilyTree.php` |
| GEDCOM upload | `extensions/gedcom/SpecialGedcomPage.php` |
| Search interface | `extensions/other/SpecialSearch.php` |
| Merge pages | `extensions/other/SpecialMerge.php` |
| AJAX dispatcher | `includes/AjaxDispatcher.php` |
| Hook registration | `extensions/other/Hooks.php` |