174 lines
6.2 KiB
Markdown
174 lines
6.2 KiB
Markdown
# NoteLett Release Notes Template And Production Deploy Checklist
|
|
|
|
Date: May 5, 2026
|
|
Product: NoteLett (`notelett`)
|
|
|
|
## Release Notes Template
|
|
|
|
```markdown
|
|
# NoteLett Release YYYY.MM.DD
|
|
|
|
## Summary
|
|
|
|
- What changed:
|
|
- Who is affected:
|
|
- Primary operator:
|
|
- Release commit:
|
|
|
|
## User-Facing Changes
|
|
|
|
- Web:
|
|
- Mobile:
|
|
- Backend/API:
|
|
- AI/Smart Actions:
|
|
|
|
## Operational Changes
|
|
|
|
- New or changed environment variables:
|
|
- Data migrations or backfills:
|
|
- Feature flags or kill switches:
|
|
- Monitoring dashboards/alerts:
|
|
|
|
## Verification
|
|
|
|
- Backend typecheck/test/build:
|
|
- Web typecheck/test/build/E2E:
|
|
- Mobile lint/typecheck/test:
|
|
- Docker image build:
|
|
- Compose smoke:
|
|
- Platform dependency smoke:
|
|
- Secret/color/token audits:
|
|
|
|
## Known Deferrals Or Risks
|
|
|
|
- Deferral:
|
|
- Owner:
|
|
- Follow-up issue/roadmap item:
|
|
|
|
## Rollback Plan
|
|
|
|
- App/backend rollback target:
|
|
- Database rollback/backfill reversal:
|
|
- Feature flag or kill-switch action:
|
|
- Smoke checks after rollback:
|
|
```
|
|
|
|
## Required Environment Variables
|
|
|
|
Backend production must fail closed unless these are configured intentionally:
|
|
|
|
| Variable | Notes |
|
|
| --- | --- |
|
|
| `NODE_ENV=production` | Production validation is stricter than local compose smoke. |
|
|
| `PORT=4016` and `HOST=0.0.0.0` | Match service routing and container health checks. |
|
|
| `PRODUCT_ID=notelett` and `SERVICE_NAME=notelett-backend` | Product/service identity. |
|
|
| `JWT_SECRET` | Strong production secret or production auth verification equivalent. |
|
|
| `DB_PROVIDER=cosmos` | Production must not use memory datastore. |
|
|
| `COSMOS_ENDPOINT`, `COSMOS_KEY`, `COSMOS_DATABASE` | Cosmos database connection. |
|
|
| `FIELD_ENCRYPT_ENABLED=true` | Required for production. |
|
|
| `FIELD_ENCRYPT_KEY_PROVIDER` | Use AKV or managed production key provider. |
|
|
| `PLATFORM_SERVICE_URL` | platform-service base URL. |
|
|
| `EXTRACTION_SERVICE_URL` | extraction-service base URL. |
|
|
| `MCP_SERVER_URL` | common-platform MCP server base URL. |
|
|
| `TELEMETRY_ENABLED=true` | Enable when platform telemetry is available. |
|
|
| `FEATURE_FLAGS_ENABLED=true` | Enable when platform feature flags are available. |
|
|
| `LLM_PROVIDER` and provider credentials | Use mock only for non-production. |
|
|
|
|
Web production build/runtime must set:
|
|
|
|
| Variable | Notes |
|
|
| --- | --- |
|
|
| `NEXT_PUBLIC_NOTES_API_URL` | Browser-reachable NoteLett backend `/api` URL. |
|
|
| `NEXT_PUBLIC_PLATFORM_SERVICE_URL` | Browser-reachable platform-service `/api` URL. |
|
|
| `NEXT_PUBLIC_EXTRACTION_SERVICE_URL` | Browser-reachable extraction-service URL where used. |
|
|
| `NEXT_PUBLIC_MCP_SERVER_URL` | MCP server `/api` URL, default local port `4007`. |
|
|
| `NEXT_PUBLIC_TELEMETRY_TRANSPORT=fetch` | Production telemetry transport. |
|
|
|
|
Mobile production builds must set:
|
|
|
|
| Variable | Notes |
|
|
| --- | --- |
|
|
| `EXPO_PUBLIC_NOTES_API_URL` | Device-reachable NoteLett backend `/api` URL. |
|
|
| `EXPO_PUBLIC_PLATFORM_SERVICE_URL` | Device-reachable platform-service `/api` URL. |
|
|
|
|
Do not place secrets in `NEXT_PUBLIC_*` or `EXPO_PUBLIC_*` variables.
|
|
|
|
## Pre-Deploy Checklist
|
|
|
|
- Confirm release commit is pushed and CI is green.
|
|
- Confirm `pnpm run audit:release-guards` passes.
|
|
- Confirm `pnpm run dependency:health` has no typecheck failures; review the non-blocking outdated report.
|
|
- Confirm backend, web, and mobile tests from `docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md` P10 have passed or have explicit release-owner signoff.
|
|
- Confirm Docker images build in CI.
|
|
- Confirm common-platform services are deployed and reachable: platform-service, extraction-service, mcp-server, telemetry, diagnostics, flags, kill switch, blob.
|
|
- Confirm Cosmos database, containers, partition keys, backups, and retention policy are ready.
|
|
- Confirm field encryption provider and key material are ready.
|
|
- Confirm feature flags and kill switch defaults are safe for release.
|
|
- Confirm mobile build identifiers and URLs match `docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`.
|
|
|
|
## Migration And Seed Checklist
|
|
|
|
- Run `pnpm run seed:bootstrap` with production backend environment; see `docs/SEED_BOOTSTRAP_STRATEGY.md`.
|
|
- Built-in prompt templates and intake rules are seeded idempotently.
|
|
- Default workspace/bootstrap behavior is per-user and deterministic.
|
|
- Cosmos schema changes are backward compatible or have a documented backfill.
|
|
- Encrypted-field migrations have a dry-run and rollback note.
|
|
- Long-running backfills have owner, estimated duration, progress logs, and stop criteria.
|
|
- No migration relies on client-side public environment variables for secrets.
|
|
|
|
## Deploy Steps
|
|
|
|
1. Announce deploy window and freeze unrelated production changes.
|
|
2. Deploy common-platform dependencies first if their API contracts changed.
|
|
3. Deploy NoteLett backend image.
|
|
4. Run backend readiness and dependency checks:
|
|
- `GET /health`
|
|
- `GET /api/bootstrap`
|
|
- `GET /api/diagnostics/readiness`
|
|
5. Deploy web image and verify root route loads.
|
|
6. Publish or distribute mobile build after backend/web smoke passes.
|
|
7. Run release smoke checks:
|
|
- `docs/PLATFORM_SMOKE_CHECKS.md`
|
|
- `scripts/compose-smoke.sh` in Docker-capable environments where appropriate
|
|
- `docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`
|
|
8. Watch logs and telemetry for at least 30 minutes after deploy.
|
|
|
|
## Rollback Checklist
|
|
|
|
- Keep previous backend and web image tags available.
|
|
- Prefer feature flag or kill-switch rollback for risky UI/AI behavior before image rollback.
|
|
- If backend rollback is required, confirm the previous image can read any newly written documents.
|
|
- If a migration/backfill ran, follow its rollback section before reverting code that depends on the new schema.
|
|
- After rollback, rerun:
|
|
- `GET /health`
|
|
- `GET /api/bootstrap`
|
|
- one authenticated workspace/note flow
|
|
- web root smoke
|
|
- mobile auth and note list smoke if mobile users were affected
|
|
|
|
## Monitoring Links To Fill Per Environment
|
|
|
|
| Area | Link |
|
|
| --- | --- |
|
|
| Backend logs | TBD |
|
|
| Web logs | TBD |
|
|
| platform-service logs | TBD |
|
|
| extraction-service logs | TBD |
|
|
| mcp-server logs | TBD |
|
|
| Cosmos metrics | TBD |
|
|
| Telemetry dashboard | TBD |
|
|
| Diagnostics dashboard | TBD |
|
|
| Error/crash reporting | TBD |
|
|
| CI workflow run | TBD |
|
|
|
|
## Release Record
|
|
|
|
After release, append a record or link to the release notes containing:
|
|
|
|
- release commit hash
|
|
- deployed image tags/build ids
|
|
- migration/backfill ids
|
|
- smoke result summary
|
|
- incidents or rollback actions
|
|
- follow-up tasks
|