Lesson 34 — Performance, diagnostics, migrations, packaging

Outcome

Turn the working system into a dependable Linux daily-driver build with measured performance and upgrade confidence.

Why this comes now

Only now do we know what needs hardening. Premature packaging/observability would have optimized architecture that was still moving.

Understand

Hardening includes database migration fixtures, structured diagnostics, performance regression scenarios, backup/recovery, Electron/core lifecycle, and packaging. Large raw logs/history require bounded retention/read behavior without deleting evidence unexpectedly.

Packaging should keep the Go core independently executable while bundling it with Electron.

Build the real project

1. Add old-schema DB fixtures and upgrade tests.
2. Version long-lived JSON payload schemas.
3. Add structured logging + diagnostic export that avoids casually leaking secrets.
4. Profile core memory/goroutines and UI long-history behavior.
5. Add explicit limits/retention settings where evidence requires them.
6. Add DB backup/restore guidance.
7. Package AppImage first for the target Linux environment; then .deb/AUR only as useful.
8. Test clean install, upgrade, crash/restart, and uninstall without destroying project repositories/worktrees unexpectedly.

Completion gate

A packaged build completes the core acceptance loop. Old DB fixtures migrate. Large-history perf scenario stays within documented expectations. Diagnostic bundle can explain a failed Operation/Run without reading the database manually.

Pitfalls to avoid

Do not add a self-updater before basic packaging is reliable. Do not log provider secrets/tokens. Do not load huge native modules into Electron main casually; isolate risky native capability if introduced.

References

Electron packaging docs: https://www.electronjs.org/docs/latest/tutorial/application-distribution ; modernc SQLite: https://modernc.org/sqlite ; Vibe migration failure example: https://github.com/BloopAI/vibe-kanban/issues/2972 ; memory/long-session example: https://github.com/BloopAI/vibe-kanban/issues/3352

Checkpoint

M13 is complete when you can install Forge on your normal Linux environment and trust it with a real small project.