diff --git a/UPGRADE.md b/UPGRADE.md index b577ace..f150b5d 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -78,14 +78,129 @@ resolves to `8.x`, which is too new for Meteor's 7-style helper layout — pin t REST smoke test: **byte-identical to baseline.** ✅ +### Escala 2 — 1.8.3 → 1.11 (version resolution only) + +```bash +meteor update --release 1.11 +``` + +Resolution reached 1.11 (`ecmascript` 0.14.3, `mongo` 1.10.0, `npm-mongo` +**3.8.0** — still Mongo-3.2-compatible, `accounts-*` 1.x, `email` 2.0). But this +release surfaced the two big blockers below. The app was ultimately driven to +**2.3** (see next section); 1.11 was a transit point, not a landing. + +### Escala 3 — → Meteor 2.3 ✅ green (builds + runs against Mongo 3.2, smoke byte-identical) + +`.meteor/release = METEOR@2.3`. `npm-mongo` **3.9.0** (mongodb driver 3.x) — the +last driver line that still speaks to a Mongo 3.2 server. Core bumps: +`accounts-*` 2.0, `ecmascript` 0.15.2, `mongo` 1.12.0, HMR added. + +This escala was dominated by **dead Atmosphere packages** (the plan's #1 risk). +Root causes and fixes, in the order they were hit: + +1. **`arkham:comments-ui` — no Meteor 2.x build.** The vendored local package + used `Npm.depends`, and rebuilding a *local* package's npm deps crashes + meteor-tool ≥1.11 on this host (`node_contextify.cc … Assertion + args[1]->IsString()` → SIGABRT; reproducible with any `Npm.depends`, even + `is-number`). Switching to the Atmosphere isopack avoided the local rebuild + but the package is abandoned: its newest 2.x-solvable version (0.2.15) pins + `accounts-password@1.0.1`, conflicting with Meteor 2.0's accounts-password 2.0. + **Decision (user-approved): reimplement comments as a small React feature** + (`imports/api/Comments/*`, `imports/ui/components/Comments/CommentsBox.js`), + dropping the package entirely. Fire-page comments only (the sole usage), with + likes/dislikes, image/YouTube embed, owner edit/remove, and the + "email other commenters" side-effect preserved. Comment text is now rendered + as **safe plain text** (+ media embed) instead of markdown-to-HTML — a small + scope reduction and a security improvement (no raw-HTML injection of user + content). The old local fork is preserved in its nested git repo + (commit `4761da9`). + +2. **`coffeescript@1.0.17` build plugin — crashes the build.** The same + `node_contextify` assertion fired at *build start* on this host whenever the + coffeescript compiler plugin loaded. It was pulled transitively by the dead + **test stack** (`meteortesting:mocha`, `practicalmeteor:chai`, + `xolvio:cleaner`) and by the old auto-downgraded `nimble:restivus@0.6.6` + (which needs `iron:router`). Removing those removed coffeescript and + unblocked the build. A trivial `meteor create` app builds fine on the same + tool, confirming the crash is package-specific, not a broken tool. + +3. **`nimble:restivus` — the REST API package — pins `accounts-password@1.3.3`** + (incompatible with 2.x) and is CoffeeScript (needs the crashing plugin). + **Vendored** as `packages/nimble-restivus`: the `.coffee` sources were + precompiled to plain JS (`lib/restivus-all.js`, single translation unit so + the `Auth`/`Route`/`Restivus` classes share scope; `Restivus` left + un-`var`'d so Meteor's `api.export` picks it up), and `package.js` loosens + `accounts-password` to 2.x and drops the coffeescript dependency. This also + let restivus resolve to 0.8.12 (json-routes based), which **removed the whole + `iron:router` stack**. REST behavior unchanged (smoke byte-identical). + +4. **`maximum:server-transform` (unused) removal** broke + `Meteor.publishTransformed` in `FalsePositives/server/publications.js`; no + transform was actually configured, so replaced with plain `Meteor.publish`. + +5. **`fourseven:scss` 4.5.4 → 4.14.1** — `node-sass@4.5.3` won't build on node 12 + (Meteor ≥1.9); 4.14.1 uses a node-12-compatible node-sass with prebuilt + binaries. (Meteor 1.8 built it on node 8.) `4.15.0` needs ecmascript ≥ 0.15.1 + → too new for 1.11. + +6. **`less`, `markdown` removed** — no `.less`/`.md` source files; their build + plugins were dead weight. + +### ⚠️ Local build-host caveat + +Meteor-tool's bundled node (12.x/14.x) SIGABRTs (`node_contextify` assertion) on +this machine (kernel 6.12) when certain old build plugins load — this is an +environment interaction, not a code defect (the deploy host built these fine +historically). It was fully worked around by removing the dead build plugins +above. If a future escala hits it again, build in a container matching the +deploy target (Debian) rather than on this host. + +## Escala ceiling vs Mongo 3.2 + +Meteor bumps the bundled `mongodb` Node driver to **4.x at Meteor 2.5**, which +drops support for servers **< 3.6**. Production's rsmain is **Mongo 3.2**. +Therefore the highest Meteor that can talk to the current production DB is +**~2.4** (npm-mongo/driver 3.x). The smoke test runs against a real `mongo:3.2`, +so the exact ceiling is verified empirically: it stays green through 2.3; +2.5+ is expected to fail at connection time. **Landing target: highest 2.x that +keeps the smoke test green against Mongo 3.2.** + +## 🚧 3.x — blocked (do not run `meteor update --release 3.x`) + +Two independent blockers, both external/coordination: +1. **MongoDB 3.2 → ≥ 4.4.** Meteor 3's driver requires it. Shared Comunes infra + (rsmain) — coordinate the DB upgrade in a separate phase. This *also* gates + Meteor 2.5+. +2. **Notifications cutover.** The old notif code is already removed from this + branch; production must not run this build until `tcef-notifications` is + emitting in prod. + +When Mongo is ≥ 4.4 and the notifications service is live in prod, the remaining +3.x work is: `meteor update --release 3.x`, finish the async/await migration of +server code (collections/methods/publications `*Async`, no Fibers), React 18 +render root, and re-run the smoke test. + ## Dependency debt (tracked, to resolve in the noted escala) | Dep | From | Target | Status | |---|---|---|---| -| React / react-dom | 16.0 | 18 | pending (escala 1.11) | -| raven / flowkey:raven | 2.4 | @sentry/node + @sentry/react | pending — DSN off until GlitchTip/Sentry back | +| React / react-dom | 16.0 | 18 | **debt** — deferred; ancient react-* libs (react-bootstrap 0.31, reactstrap 5-alpha, react-leaflet 1.8) break on 18. React 16 works through Meteor 2.x/3.x. Own front-end project. | +| Server async/await | Fibers | `*Async` APIs | **pending** — prep for 3.x; 2.x still runs on Fibers so not yet required. | +| raven / flowkey:raven | 2.4 | @sentry/node + @sentry/react | debt — DSN off until GlitchTip/Sentry back (sentry.comunes.org dead → harmless boot-log timeout noise) | | nodemailer | 4 | 6+ | pending | -| Babel | 7 beta | 7 stable | pending (first escala that allows) | -| i18next | 10 | current | evaluate cost; pin + note as debt if it breaks a lot | -| Leaflet | 1.3.1 | current | evaluate cost; pin + note as debt if it breaks a lot | +| Babel | 7 beta | 7 stable | ✅ done (escala 1) | +| i18next | 10 | current | debt — pin; not on the critical path | +| Leaflet | 1.3.1 | current | debt — pin; not on the critical path | +| arkham:comments-ui | 1.4.x | — | ✅ replaced with in-repo React feature | +| nimble:restivus | Atmosphere | vendored | ✅ local precompiled package, accounts-password 2.x | +| maximum:server-transform, meteorhacks:zones, less, markdown, test stack | — | — | ✅ removed (dead/unused) | +| fourseven:scss | 4.5.4 | 4.14.1 | ✅ node-12 compatible | | node-gcm | 1.0.2 | — | ✅ removed (dead API, moved to microservice) | + +### Comments React feature — verification note + +The server builds and the REST smoke test is green, and the client bundle +compiles, but the comments UI itself is **not exercised by the smoke test** +(it's not part of the Flutter REST contract). It needs manual staging +verification: on a fire archive page — logged-in post/edit/remove, like/dislike, +and image/YouTube embed.