# TG Bot — Merge & Deployment Checklist

Follow these steps IN ORDER every time we're ready to merge dev → prod.
Never skip steps, never edit prod directly.

---

## Step 1 — Commit on dev

```bash
cd /opt/docker/tg-bot-ts-dev
git add -A
git commit -m "<message>"
git push origin dev
```

**Commit message conventions:**
- `feature: short description` — new player-facing feature
- `fix: short description` — bug fix
- `housekeeping: short description` — internal/admin-only addition, refactor, maintenance
- For multi-topic commits, use a body:
  ```
  fix: unify score submission, fix TGScore type drift, fix playedBy semantics

  - Score.submit/score/set.ts/score-inject.ts now share one code path
  - TGScore consolidated to single canonical type
  - playedBy now correctly identifies the actual player on borrowed characters
  - Attendance.allSubmitted matches against playedBy (borrower) not just userKey
  ```

---

## Step 2 — Merge to prod

```bash
cd /opt/docker/tg-bot-ts
git fetch origin
git merge origin/dev
docker compose up -d --build
docker compose restart
```

---

## Step 3 — Run maintenance scripts (ALWAYS after merge)

```bash
python3 scripts/migrate-stats-shape.py /opt/docker/tg-bot-ts/data
python3 scripts/fix-class-keys.py /opt/docker/tg-bot-ts/data
python3 scripts/migrate-history-shape.py /opt/docker/tg-bot-ts/data
```

These are safe to re-run (idempotent). The class-key script is especially important —
see the Known Bug note below. `migrate-history-shape.py` (added 2026-07-31) backfills
`tg-history/*.json` files that only have a `scores` array — caused by `Score.submit`
not writing the full result shape on a file's first write; the code path is now fixed,
this just repairs files created before the fix. Found 50 affected files in dev alone,
so prod almost certainly needs this run too.

---

## Step 4 — Verify prod is healthy

```bash
docker logs tg-bot-ts --tail 50 2>&1
# or via alias:
tg-prod-logs
```

Look for: no TypeScript compile errors, no unhandled exceptions on startup,
"Bot ready." in the logs, poll state restored correctly if a poll was active.

---

## Step 5 — Post changelog and announcements (if applicable)

```
/tg-admin updates post version:vX.X.X
/tg-admin announcement post id:XXX-announcement-id
```

Only post what's new since the last prod deploy — don't re-post already-posted versions.

---

## Known Bug — Class object serialization (recurring, must run fix-class-keys.py every merge)

Files are still being written with the UNSERIALIZED `CharacterClass` object shape instead
of the plain `ClassKey` string. Example of the broken shape:

```json
"characterClass": {
  "key": "DM",
  "name": "Dark Mage",
  "shortName": "DM"
}
```

Expected shape (everywhere in `wrank.json` and `tg-history/*.json`):

```json
"class": "DM"
```

This causes class emojis to silently disappear from Leaderboard/Result embeds.
`scripts/fix-class-keys.py` normalizes these on every run — run it after EVERY merge
until the systemic fix (a proper `serializeCharacter`/`hydrateCharacter` pair at every
read/write boundary) is implemented.

The systemic fix is tracked in REFERENCE.md under PENDING items.

---

## Quick reference — shell aliases (both stacks, defined in ~/.bashrc)

```bash
tg-dev-logs          # docker logs tg-bot-ts-dev --follow
tg-prod-logs         # docker logs tg-bot-ts --follow
tg-dev-restart       # docker compose restart (dev)
tg-prod-deploy       # fetch + merge + build + restart (prod)
tg-dev-register      # register slash commands on dev
tg-prod-register     # register slash commands on prod
tg-dev-upload-emojis
tg-prod-upload-emojis
tg-dev-split-emojis
```