Upgrading
Review upstream changes and migrations while preserving product settings, resource identity, and data.
Upgrade with Git
Flare is an independent source repository. Product branding, configuration, and business code diverge from upstream over time. Compare and merge rather than overwriting a deployed project with a fresh download. Record the current commit and target and save local work first.
Inspect upstream changes
If upstream is already configured:
git fetch upstream
git log --oneline HEAD..upstream/main
git diff --stat HEAD...upstream/main
git switch -c chore/flare-upgradeChoose the actual available update branch; do not assume a development branch has reached main. After review, merge or cherry-pick explicit commits. Resolve schema, order, and authorization conflicts according to both business intents rather than accepting one side mechanically.
Review by responsibility
| Area | Check |
|---|---|
| Config, overrides, MDX | Preserve your name, offers, provider mappings, and content |
| Auth and server APIs | Login behavior, authorization, Origin, limits, and variable names |
| Database and migrations | SQL, populated data, backward compatibility |
| Billing, credits, jobs | Signatures, ledger, idempotency, compensation, outbox |
| Components and styles | Current aliases, Base UI, and theme behavior |
| CLI and target-resources | Existing names/account and new planning behavior |
The current UI update moves primitives to apps/web/src/components/ui while packages/ui retains helpers. Email-code sign-in is now the default; password login lives at /auth/password. Update help and tests alongside those commits instead of retaining stale imports or login instructions.
From 2026-10-20 (b6b68e5) to the AI release (a2276f4)
This range adds the AI studios and changes several ownership boundaries. Review it as separate areas rather than one merge:
| Area | Change | Action |
|---|---|---|
| API | server/api.ts became a small composer; endpoints moved to server/routes/*.ts | Move custom endpoints into the owning route module or a new registered module |
| Workbench | Grouped sidebar; image, video, voice and chat studios; /app/library; sections load on demand | Re-check custom workbench pages and navigation entries |
| AI | OpenAI defaults in packages/ai: gpt-6-luna, GPT Image 2.5 Flare, gpt-4o-mini-tts; optional Workers AI and other adapters remain | Set OPENAI_API_KEY; images now cost 20 credits, speech 5 per 1,000 characters and outputs WAV. Recheck margins, budgets and the speech migration deadline. |
| Billing | Credit packs (kind: "pack"), credits fixed on the order, labeled ledger rows | Add kind to custom catalog entries and set reason/ref in any custom ledger writer |
| Database | Migrations 0009 to 0013 add ai_tasks, ai_assets, order credits, ledger labels, cost estimates and video polling columns | All are additive; apply them with the normal reviewed flow |
| Configuration | ai.* settings, AI_MODE, FLARE_DEV_PORT, optional provider keys in .env.example | Add only what you use; mock mode keeps local work free |
| Public site | /ai/image, /ai/video, /ai/voice, /ai/chat, AI tools menu, formal pricing | Rewrite modules/public/copy.ts for your product |
Welcome credits are now granted after email verification instead of at registration.
Preserve machine and production settings
Ignored .env, .dev.vars, and .muse state do not arrive through Git. Compare the new .env.example with existing variable names, adding required inputs without rotating production AUTH_SECRET. Review resource-name changes carefully so template defaults do not replace your database/bucket.
Install the committed lockfile with pnpm install --frozen-lockfile. Build first when generated modules are absent. Schema changes need reviewed migrations; do not generate unreviewed SQL directly during production deployment.
Validate and release
Run the relevant test layers, including the compiled Worker, and focus on changed authentication, payment, and task behavior. Review doctor and plan for unexpected resources or risky migrations before your release process.
Keep a code rollback reference and evaluate database recovery separately. After publication, inspect public smoke and real integrations. Record commit range, migrations, executed outcomes, and outstanding acceptance rather than copying old passing counts.