docs(release): add deploy checklist template
This commit is contained in:
parent
2c01ffb0eb
commit
606828401e
@ -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
|
||||
|
||||
172
docs/RELEASE_CHECKLIST.md
Normal file
172
docs/RELEASE_CHECKLIST.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user