305 lines
12 KiB
Markdown
305 lines
12 KiB
Markdown
# Release Checklist
|
||
|
||
**Owner:** Release Committee
|
||
**Applies to:** `kell_web` (Flutter Web / Windows Desktop) and `kell_mobile` (Flutter Android)
|
||
**Last reviewed:** 2026-08-29
|
||
**Review cycle:** Every release; document reviewed at least quarterly
|
||
|
||
---
|
||
|
||
## Purpose
|
||
|
||
This document defines the **mandatory gates** a build must pass before it is
|
||
promoted into each target environment. Each environment inherits every gate from
|
||
the environment before it, then adds its own.
|
||
|
||
Promotion is **sequential**: Development → Test/QA → Staging → Production. A
|
||
build may not skip an environment.
|
||
|
||
---
|
||
|
||
## 1. Environment Matrix
|
||
|
||
| Environment | Target | `KC_ENV` | Square mode | Data | Audience | Approver |
|
||
| --------------- | --------------------------------- | --------------------- | ------------ | ----------------------- | ------------- | ----------------- |
|
||
| **Development** | Local workstation | `fake` | n/a | In-memory fakes | Engineer | Self |
|
||
| **Test / QA** | CI runner + internal test devices | `wordpress` | n/a | WooCommerce staging | Engineer + QA | Engineering lead |
|
||
| **Staging** | Pre-production host + test device | `multi` | `sandbox` | Staging WC + Square SBX | QA + business | Release committee |
|
||
| **Production** | Live web host + Play Store track | `wordpress` / `multi` | `production` | Live WC + Square live | Operators | Release committee |
|
||
|
||
> **Rule:** `KC_SQUARE_ENVIRONMENT=production` is permitted **only** in the
|
||
> Production environment. Any lower environment using a live Square token is an
|
||
> immediate stop-ship defect.
|
||
|
||
---
|
||
|
||
## 2. Universal Gates (all environments)
|
||
|
||
These must pass before any promotion.
|
||
|
||
- [ ] `dart analyze --fatal-infos` is clean for all 11 packages and both apps
|
||
- [ ] Full test suite passes — current baseline **1,475 / 1,475**
|
||
- [ ] No test is skipped, `@Skip`-ed, or commented out without a linked issue
|
||
- [ ] `docs/development/build_execution_tracker.md` has a slice entry for the change
|
||
- [ ] `docs/development/master_development_brief.md` reflects the new baseline
|
||
- [ ] No secrets committed — credentials supplied only via `--dart-define`
|
||
- [ ] No `TODO`/`FIXME` introduced without a linked tracker item
|
||
|
||
Commands:
|
||
|
||
```bash
|
||
cd kell_creations_apps
|
||
./tools/run_all_tests.sh --analyze
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Development Environment
|
||
|
||
**Purpose:** Fast inner-loop work against in-memory fakes. No external calls.
|
||
|
||
### Build
|
||
|
||
```bash
|
||
flutter run -d chrome --dart-define=KC_ENV=fake # kell_web
|
||
flutter run -d android --dart-define=KC_ENV=fake # kell_mobile
|
||
```
|
||
|
||
### Gates
|
||
|
||
- [ ] Universal gates pass
|
||
- [ ] Feature branch is cut from current `main`
|
||
- [ ] Slice is vertical and reviewable (domain → application → data → presentation)
|
||
- [ ] New public APIs carry doc comments
|
||
- [ ] Environment badge renders `FAKE`
|
||
- [ ] "Report a problem" action opens the dialog and submits successfully
|
||
- [ ] No unexpected `ERROR`/`FATAL` records in the console during a smoke pass
|
||
|
||
### Exit criteria
|
||
|
||
Analyze clean, tests green, tracker updated. Open PR into `main`.
|
||
|
||
---
|
||
|
||
## 4. Test / QA Environment
|
||
|
||
**Purpose:** Validate real WooCommerce integration and cross-platform parity.
|
||
|
||
### Build
|
||
|
||
```bash
|
||
flutter build web --dart-define=KC_ENV=wordpress \
|
||
--dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \
|
||
--dart-define=KC_WC_CONSUMER_KEY=ck_xxx \
|
||
--dart-define=KC_WC_CONSUMER_SECRET=cs_xxx
|
||
|
||
flutter build apk --debug --dart-define=KC_ENV=wordpress \
|
||
--dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \
|
||
--dart-define=KC_WC_CONSUMER_KEY=ck_xxx \
|
||
--dart-define=KC_WC_CONSUMER_SECRET=cs_xxx
|
||
```
|
||
|
||
### Gates
|
||
|
||
- [ ] All Development gates pass
|
||
- [ ] Forgejo `Flutter Test` workflow green
|
||
- [ ] Forgejo `Flutter Analyze` workflow green
|
||
- [ ] Coverage reported in the CI summary; no unexplained decrease
|
||
- [ ] Credentials point at **staging** WooCommerce — never production
|
||
- [ ] Environment badge renders `WP`
|
||
- [ ] Missing-credential path verified: app falls back to `FAKE` **and logs a warning**
|
||
|
||
### Functional verification (WooCommerce)
|
||
|
||
- [ ] Product list loads, filters, searches, and sorts
|
||
- [ ] Single-field edits persist (name, price, description, category)
|
||
- [ ] Status transitions behave (`unpublished` → `draft`, `pendingReview` → `published`)
|
||
- [ ] Product creation completes on web (`CreateProductDialog`) and mobile (`MobileCreateProductPage`)
|
||
- [ ] Category CRUD works
|
||
- [ ] Bulk actions (move-to-draft, publish, submit-for-review) work
|
||
- [ ] API failures surface a user-visible error — never a silent failure
|
||
|
||
### Observability verification
|
||
|
||
- [ ] Startup record written with the effective environment
|
||
- [ ] A forced API failure produces an `ERROR` record with source and context
|
||
- [ ] Bug report submission attaches the recent log tail
|
||
- [ ] **Credential redaction confirmed** — no token, key, or secret appears in any log or report
|
||
|
||
### Mobile-specific
|
||
|
||
- [ ] Touch targets meet the 48×48dp minimum
|
||
- [ ] Haptics fire (`mediumImpact` state changes, `lightImpact` field edits)
|
||
- [ ] Layout is correct on a notch/gesture-bar device
|
||
- [ ] Back navigation behaves throughout
|
||
|
||
### Exit criteria
|
||
|
||
CI green, functional pass recorded, no open Critical or High defects.
|
||
|
||
---
|
||
|
||
## 5. Staging Environment
|
||
|
||
**Purpose:** Production rehearsal with both channels live in sandbox mode.
|
||
|
||
### Build
|
||
|
||
```bash
|
||
flutter build web --release --dart-define=KC_ENV=multi \
|
||
--dart-define=KC_WC_SITE_URL=https://staging.kellcreations.com \
|
||
--dart-define=KC_WC_CONSUMER_KEY=ck_xxx \
|
||
--dart-define=KC_WC_CONSUMER_SECRET=cs_xxx \
|
||
--dart-define=KC_SQUARE_ACCESS_TOKEN=EAAAl_sandbox_xxx \
|
||
--dart-define=KC_SQUARE_LOCATION_ID=L_xxx \
|
||
--dart-define=KC_SQUARE_ENVIRONMENT=sandbox
|
||
```
|
||
|
||
The Android build uses the same defines with `flutter build apk --release`.
|
||
|
||
### Gates
|
||
|
||
- [ ] All Test/QA gates pass
|
||
- [ ] Built in **release** mode (not debug/profile)
|
||
- [ ] `KC_SQUARE_ENVIRONMENT=sandbox` — confirmed, not `production`
|
||
- [ ] Square token is a **sandbox** token
|
||
- [ ] Environment badge renders `MULTI`
|
||
- [ ] Incomplete-credential path falls back to `FAKE` with a logged warning
|
||
|
||
### Multi-channel verification
|
||
|
||
- [ ] Square catalog sync completes; `SquareSyncStatusPanel` reports the result
|
||
- [ ] `ProductIdMapping` records are created correctly — **no duplicate listings**
|
||
- [ ] Already-synced products reuse their existing mapping (ID conflation regression check)
|
||
- [ ] Square inventory counts load and reconcile
|
||
- [ ] Partial sync failure surfaces per-item `SyncError` detail
|
||
- [ ] Integrations page reflects live sync state on web and mobile
|
||
|
||
### Mobile POS verification (sandbox)
|
||
|
||
- [ ] Product selection → cart → payment flow completes
|
||
- [ ] Cash payment records correctly
|
||
- [ ] Card payment completes against Square sandbox
|
||
- [ ] Receipt renders with the correct total
|
||
- [ ] Payment failure is handled without data loss
|
||
|
||
### Non-functional
|
||
|
||
- [ ] Release build starts within an acceptable time on a representative device
|
||
- [ ] No memory growth across an extended session
|
||
- [ ] Web build loads over the target network profile
|
||
- [ ] Offline/interrupted-network behaviour is understood and documented
|
||
|
||
> **Known limitation:** Offline caching and the sales queue (Stage 14) are **not
|
||
> implemented**. Network loss during a market sale is currently unrecoverable.
|
||
> This must be stated in release notes for any field use.
|
||
|
||
### Exit criteria
|
||
|
||
Business sign-off recorded, no open Critical/High defects, rollback plan agreed.
|
||
|
||
---
|
||
|
||
## 6. Production Environment
|
||
|
||
**Purpose:** Live operator use against real customers and real money.
|
||
|
||
### Pre-flight
|
||
|
||
- [ ] All Staging gates pass
|
||
- [ ] Release committee approval recorded
|
||
- [ ] Release notes drafted, including known limitations
|
||
- [ ] Rollback plan documented and the previous artifact retained
|
||
- [ ] Version bumped in both `pubspec.yaml` files
|
||
- [ ] `AppServices.appVersion` and `MobileAppServices.appVersion` match `pubspec.yaml`
|
||
- [ ] Release tagged in Git
|
||
|
||
### Credential and safety gates
|
||
|
||
- [ ] Production WooCommerce credentials sourced from the secret store — **not** the repo
|
||
- [ ] `KC_SQUARE_ENVIRONMENT=production` set deliberately
|
||
- [ ] Square production token scoped to the minimum required permissions
|
||
- [ ] Square location ID matches the intended physical location
|
||
- [ ] A staging credential is confirmed absent from the production build
|
||
- [ ] Credential redaction verified once more in the production artifact
|
||
|
||
### Build
|
||
|
||
```bash
|
||
flutter build web --release --dart-define=KC_ENV=multi \
|
||
--dart-define=KC_WC_SITE_URL=https://store.kellcreations.com \
|
||
--dart-define=KC_WC_CONSUMER_KEY=$WC_KEY \
|
||
--dart-define=KC_WC_CONSUMER_SECRET=$WC_SECRET \
|
||
--dart-define=KC_SQUARE_ACCESS_TOKEN=$SQUARE_TOKEN \
|
||
--dart-define=KC_SQUARE_LOCATION_ID=$SQUARE_LOCATION \
|
||
--dart-define=KC_SQUARE_ENVIRONMENT=production
|
||
```
|
||
|
||
The Android release build uses the same defines with `flutter build appbundle --release`.
|
||
|
||
### Post-deployment verification
|
||
|
||
- [ ] App loads and the environment badge is correct
|
||
- [ ] A read-only operation succeeds (product list loads)
|
||
- [ ] A single low-risk write succeeds and is confirmed in WooCommerce admin
|
||
- [ ] Square sync runs once and mappings are correct
|
||
- [ ] **One low-value real transaction** processed end-to-end and reconciled in Square
|
||
- [ ] Bug reporting works from the production build
|
||
- [ ] No `ERROR`/`FATAL` records during the verification pass
|
||
|
||
### Monitoring window
|
||
|
||
- [ ] Observed for the first operating session
|
||
- [ ] Bug report queue reviewed before sign-off
|
||
- [ ] Operators briefed on "Report a problem" and known limitations
|
||
|
||
### Rollback triggers
|
||
|
||
Roll back immediately on any of:
|
||
|
||
- Incorrect pricing, inventory, or payment amounts
|
||
- Duplicate product listings from a sync defect
|
||
- Failed or double-charged payments
|
||
- Credential leakage in any log or report
|
||
- Any Critical defect without a workaround
|
||
|
||
---
|
||
|
||
## 7. Release Sign-Off Record
|
||
|
||
| Field | Value |
|
||
| ------------------ | ------------------- |
|
||
| Release version | |
|
||
| Git tag / commit | |
|
||
| Target environment | |
|
||
| Test result | \_\_ / 1475 passing |
|
||
| Analyze result | |
|
||
| Known limitations | |
|
||
| Approver | |
|
||
| Date | |
|
||
|
||
---
|
||
|
||
## 8. Open Release Blockers
|
||
|
||
Carried from `PROJECT_STATE_AUDIT.md`. Each must be closed or explicitly accepted
|
||
as a documented limitation before the affected environment is used in earnest.
|
||
|
||
| ID | Item | Blocks |
|
||
| ----- | ------------------------------------------------------------- | -------------------------- |
|
||
| P2.5 | `WooCommerceOrdersRepository` not wired into `AppServices` | Test/QA orders workflow |
|
||
| P2.6 | `WooCommerceInventoryRepository` not wired into `AppServices` | Test/QA inventory workflow |
|
||
| P2.8 | Offline cache and sales queue not implemented (Stage 14) | Production field use |
|
||
| P3.2 | `SecureCredentialStore` not implemented | Production |
|
||
| P3.3 | Auth guard not wired into either shell | Production |
|
||
| P3.1 | `RetryPolicy` / `RateLimiter` not wired into API clients | Staging, Production |
|
||
| P3.6 | `feature_policy` has only a smoke test | Test/QA |
|
||
| P2.10 | Policy register CSVs contain headers only | Governance compliance |
|
||
|
||
> **Committee position:** With Stage 16A complete, the platform now has error
|
||
> logging and bug reporting. It is **approved for Development and Test/QA**.
|
||
> **Staging is conditionally approved** pending P3.1. **Production is not
|
||
> approved** until P3.2, P3.3, and P2.8 are closed — the platform currently has
|
||
> no authentication guard, no secure credential storage, and no offline
|
||
> resilience for in-person sales.
|