diff --git a/website/UPGRADE_NOTES.md b/website/UPGRADE_NOTES.md index e48b64f..a92e9cf 100644 --- a/website/UPGRADE_NOTES.md +++ b/website/UPGRADE_NOTES.md @@ -13,6 +13,111 @@ action, whether it is required, and what happens if you do nothing. --- +## Engagement: rules, an in-app inbox, and three things that arrive switched off + +**Required.** The engagement workstream, Phases 1–12. Three separate actions, and the two that matter +most are the ones nothing will tell you about. + +### What changed + +The site now has a general notification engine. A **trigger** fires (a forum post, a house going +IDOC, a governor being appointed), a **rule** decides who hears about it and through which +**channel**, and a **template** decides what it says. All of it is admin-editable under +**Admin → Engagement** — Rules, Audiences, Templates, Triggers, Send Log and Suppressions. + +Players get an in-app inbox at **Account → Notifications**, with per-channel switches at **Account → +Notification settings**, and the same inbox in the Android app. + +### What you must do + +Three things, in this order. The first is a required upgrade step for anyone running a shard; the +second and third are only required if you were relying on the behaviour they change. + +#### 1. Update the shard — the wire protocol is now 5 + +**Required if this deployment has a shard connected.** Update in this order: + +1. the website (this image), +2. the **UO module to 0.5.0** — **Admin → Modules**, paste the 0.5.0 release install-manifest + URL, then **restart the server**: modules are read from disk at boot, so nothing changes until + you do. It declares `coreApi ^1.9.0`, and a core older than that will refuse to *load* it (the + install itself still succeeds) — the module then shows as failed on that screen, naming the + version it needs. That is the check working, but it means step 1 has to be finished first; +3. the **shard**, with `installer update` on the shard host. That is what pairs a protocol-5 sidecar + with a protocol-5 overlay; the installer refuses to pair a mismatched one by design. + +**The order matters, and step 2 is the one that starts the clock.** The protocol pin lives in the UO +module's schema: on the first boot after the module updates, `uo_link_config.protocol` moves to 5 and +the site starts sending `X-UOLink-Version: 5`. A shard still on 4 answers `409` from that moment on, +so shard data stops. Nothing is lost and nothing is corrupted — the site degrades to showing the +shard offline, exactly as it does when the sidecar is down — but it stays that way until the shard is +updated. If you cannot update the shard in the same window, update the site and leave the module on +its current version until you can. + +Protocol 5 adds a decay schedule and owner account to `house.decay`, fee and owner state to +`vendor.listing`, and a new `account.login.result`. Those three fields are what the shard-driven +rules are built on; a shard on 4 could not feed them. + +#### 2. Team notification email arrives switched off + +**Required if your Teams rely on email.** Team email used to send automatically. It now runs through +the engagement engine like everything else, as four rules — and like every rule on the platform, they +are seeded **disabled**. Nothing mails until an operator switches one on. + +Open **Admin → Engagement → Rules** and enable the Team rules you want. A banner on that screen says +the same thing while they are all off, and disappears when one is enabled. + +**Only email moved.** The push tickle and the Discord bridge are unchanged and kept working through +the upgrade, so the app and your Discord channel behave exactly as before. Per-member Team +preferences and unsubscribe links still apply above the rules. + +#### 3. News push stops until you switch it on + +**Required if you publish news and expect it to notify.** Publishing a news post used to send a push +tickle directly. That call is now an engagement trigger, seeded — again — as a **disabled** rule. A +deployment that upgrades and does nothing else tickles nobody on the next publish. + +Same screen: **Admin → Engagement → Rules**, enable the news rule. + +This is deliberate rather than an oversight. The alternative was to keep the old direct tickle beside +the new trigger for one release, and an exception with no owner is one nobody removes. + +### Behaviour changes that need no action + +- **An unsubscribe link now turns off one channel, not everything.** The old link muted a user + outright, which silenced push as well as mail. It now switches off exactly the channel the link was + in. +- **Email and push are opt-in; the in-app inbox is on.** A user who changes nothing receives in-app + items and no mail. That matches the Team preference model already in use, and it is why enabling a + rule does not by itself produce a mail storm. +- **A rule cannot mail more people than its trigger allows.** Every trigger declares an audience + ceiling, and a rule is checked against it — so a staff-only event cannot be given a public + audience, whatever the rule says. +- **Bounces now suppress an address.** A hard bounce or a rejected recipient stops further mail to + that address and is listed under **Admin → Engagement → Suppressions**, which is also the only + screen that can lift one. An address that has stopped receiving mail is the first thing to check + there. + +### If you do nothing + +The site upgrades, the in-app inbox works, and no mail is sent — because every rule is off and email +needs both a transport (see the SMTP entry below) and a user who opted in. What you lose silently is +**Team email** and **news push**, both of which were sending before the upgrade and stop at it. If +you also leave the UO module on its current version, the shard keeps working on protocol 4 and none +of the shard-driven rules exist yet. + +### Data + +Nothing is dropped and no row is deleted. New tables cover rules, segments, templates, the outbox, +the send log, cooldowns, suppressions, per-channel preferences and the in-app inbox. +`team_notification_prefs` is kept and still consulted — per-Team granularity did not move. + +**Nothing in this schema expires on its own.** Finished outbox rows, the send log and the suppression +list are kept until you remove them; there is no retention sweep. On a busy deployment those tables +grow without limit, which is worth knowing before it is worth acting on. + +--- + ## Email addresses are now unique, and some accounts may lose theirs **Required only if the dashboard says so.** Engagement Phase 1b.