learning_ai_notes/docs/RELEASE_CHECKLIST.md

NoteLett Release Notes Template And Production Deploy Checklist

Date: May 5, 2026 Product: NoteLett (notelett)

Release Notes Template

# 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 in docs/DATA_MIGRATION_AND_BACKFILL_PLAN.md.
• 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