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 telemetry events and diagnostic breadcrumbs follow docs/TELEMETRY_AND_DIAGNOSTICS_TAXONOMY.md.
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

Announce deploy window and freeze unrelated production changes.
Deploy common-platform dependencies first if their API contracts changed.
Deploy NoteLett backend image.
Run backend readiness and dependency checks:
- GET /health
- GET /api/bootstrap
- GET /api/diagnostics/readiness
Deploy web image and verify root route loads.
Publish or distribute mobile build after backend/web smoke passes.
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
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

6.4 KiB Raw Blame History