diff --git a/README.md b/README.md index b4b3daa..f0f141c 100644 --- a/README.md +++ b/README.md @@ -134,3 +134,4 @@ Current baseline note: after common-platform workspace alignment, `pnpm install - [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md) — Active production-readiness checklist - [`docs/PLATFORM_SMOKE_CHECKS.md`](docs/PLATFORM_SMOKE_CHECKS.md) — Shared platform and NoteLett smoke commands - [`docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`](docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md) — Expo build notes and iOS/Android smoke checklist +- [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — Release notes template, deploy checklist, rollback, migrations, and monitoring placeholders diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000..0890f33 --- /dev/null +++ b/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,172 @@ +# 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 + +- Built-in prompt templates are seeded once and idempotently. +- Default workspace/bootstrap behavior is 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