# MediaWiki Upgrade Runbook — 1.41.1 → 1.43 (LTS) → 1.46 (latest stable)

## STATUS: ✅ COMPLETE (local) — now on 1.46.0 / PHP 8.3.30
- 1.41.1 → 1.43.9  — commit `feb17ce2`
- 1.43.9 → 1.46.0  — commit `99fad9aa` (PHP bumped to 8.3, skin 1.46 compat)
- Verified: main page, article, Special:Version, VE/Parsoid edit all 200;
  Scribunto/Lua + ImageMagick working; two-column layout + sidebar intact.
- Gotcha learned: rsync excludes MUST be root-anchored (`/cache/` not `cache/`)
  or they silently skip nested dirs like `includes/cache/`.
- **Prod upgrade is still pending** — same two-hop process against the server.


**Method:** Tarball overlay (w/ is plain core files in our repo, not a MW git clone).
**Strategy:** Local-first, one LTS hop at a time. Commit + verify after each step.
**PHP:** 8.1 satisfies both 1.43 and 1.46 (1.46 floor is PHP 8.1.0) — no image bump needed yet.

## Safety nets already in place
- Git checkpoint commit: `37b25045` (known-good 1.41.1, full rollback point)
- MySQL dump: `backups/mediawiki-pre-upgrade-1.41.sql` (789 MB)

## What we PRESERVE across the overlay (never overwrite)
- `w/skins/Protest/`         ← our custom skin
- `w/LocalSettings.php`      ← local config (gitignored, not in repo)
- `w/LocalSettings.php.bak`  ← keep local backups
- `images/` (repo root)      ← uploaded content (already a sibling of w/)
- `w/cache/`                 ← runtime cache
- Everything else in `w/` (core + all 38 bundled extensions + other skins) is
  STOCK and gets replaced by the tarball's matching versions.

---

## STEP 1 — Upgrade to 1.43

### 1a. Download + extract to a staging dir (you run this)
```bash
cd /Users/yarikb/Developer/peterlos/Protestwiki

# Get the latest 1.43.x tarball URL from https://releases.wikimedia.org/mediawiki/1.43/
# (pick the newest mediawiki-1.43.N.tar.gz)
MW143_URL="https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.3.tar.gz"

mkdir -p /tmp/mw-upgrade
curl -L "$MW143_URL" -o /tmp/mw-upgrade/mw-1.43.tar.gz
tar -xzf /tmp/mw-upgrade/mw-1.43.tar.gz -C /tmp/mw-upgrade
# extracted dir will be /tmp/mw-upgrade/mediawiki-1.43.3
ls /tmp/mw-upgrade
```

### 1b. Overlay onto w/ preserving our files (you run this)
```bash
cd /Users/yarikb/Developer/peterlos/Protestwiki
SRC=/tmp/mw-upgrade/mediawiki-1.43.3   # <-- adjust to the extracted dir name

rsync -a --delete \
  --exclude='skins/Protest/' \
  --exclude='LocalSettings.php' \
  --exclude='LocalSettings.php.bak' \
  --exclude='LocalSettings.php.prodbackup' \
  --exclude='images/' \
  --exclude='cache/' \
  --exclude='.git/' \
  "$SRC"/ w/
```
> `--delete` removes core files that 1.43 dropped. Our excludes keep the skin,
> config, uploads, and cache. `images/` at repo root is untouched regardless.

### 1c. Install PHP deps (you run this — composer, long-running)
```bash
docker compose exec mediawiki composer update --no-dev --ignore-platform-reqs -d /var/www/html/w
```

### 1d. Run the schema/DB upgrade (you run this — update.php, long-running)
```bash
docker compose exec mediawiki php /var/www/html/w/maintenance/run.php update --quick
```
> In 1.43, maintenance scripts run via `maintenance/run.php <name>`.
> If `run.php` isn't present yet, use `php maintenance/update.php --quick`.

### 1e. Verify (I help here)
- `grep MW_VERSION w/includes/Defines.php` → should read 1.43.x
- Load http://localhost:8080/wiki/Main_Page — page renders
- Load an article (e.g. Дождь) — check the Protest skin layout still holds.
  **Expected breakage:** 1.43 wraps headings in `<div class="mw-heading">`.
  Our `ArticleSectionWrapHooks` section-wrapping keys off `<h2 ...>` — I'll
  rework it for the new DOM once you confirm 1.43 is up.

### 1f. Commit the step
```bash
git add -A w/ && git commit -m "chore: upgrade MediaWiki core 1.41.1 -> 1.43.x"
```

---

## STEP 2 — Upgrade to 1.46

Same shape as Step 1, pointed at the 1.46 tarball:
```bash
MW146_URL="https://releases.wikimedia.org/mediawiki/1.46/mediawiki-1.46.N.tar.gz"
```
(Get the newest 1.46.N from https://releases.wikimedia.org/mediawiki/1.46/)

Repeat 1a–1f with `SRC=/tmp/mw-upgrade/mediawiki-1.46.N`, then:
- Re-run composer update + update.php.
- Enable Parsoid read-views / ParserMigration (1.46) — I'll wire the
  LocalSettings flags once core is up.
- Skin DOM compat pass #2 if 1.46 changed heading/media markup again.

---

## Rollback (any step)
```bash
# core files:
git reset --hard 37b25045    # or the previous step's commit
# database:
docker compose exec -T db mysql -u wikiuser -pwikipass mediawiki \
  < backups/mediawiki-pre-upgrade-1.41.sql
```