edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ecea09bbcea98d07f884648f3fa88120dbb1149
chanora/docs/release/release-readiness-go-nogo-record.md
T
EdisonJwa 82d012a46b feat(ptt): live Linux GNOME-Wayland portal session flow (DEC-025) 
Promotes the Linux backend from probe-only to a live
`org.freedesktop.portal.GlobalShortcuts` session, closing the
gen2 v0.9.3 baseline's last Linux-side code item. Both gaps I
flagged on the review pass are addressed:

  * Stop now closes the portal session through the dedicated
    `org.freedesktop.portal.Session` interface (not the
    request-cancel `Request` interface — that would only abort a
    pending Request, not release the bound shortcuts).
  * Ten new unit tests cover `classify_shortcuts_value`,
    `publish_bound`, `publish_l0`, and the `SHORTCUT_ID` stability
    contract using synthesised `OwnedValue` payloads. Live D-Bus
    coverage stays in the `linux_portal_smoke` ignored
    integration test (RR-PTT-004).

Live session lifecycle (gen2 Q5b — lazy, single backend instance):

  1. `start(gate, binding)` spawns one `tokio::spawn` worker that
     owns an async `zbus::Connection` (sharing the bridge's
     tokio runtime per Q4a).
  2. `CreateSession` with fresh random `handle_token` /
     `session_handle_token` tokens. The worker awaits the portal
     `Response` signal via a `RequestProxy` subscription and
     extracts `session_handle` from the results dict.
  3. `BindShortcuts(session_handle, [("chanora-ptt", { description
     = "Chanora push-to-talk" })], "", {})`. The portal opens its
     own system-managed dialog asking the user to choose a key
     — Chanora itself never reads raw key events. The audio
     engine continues at `L0Focused` while the dialog is open;
     the descriptor watch publishes the transition once the
     portal returns.
  4. On `response_code == 0`: classify the `trigger_description`
     substring (heuristic: contains "mouse" -> MouseSideButton,
     else Keyboard), publish `L2GlobalHoldToTalk` (or `L3` for
     mouse) through the watch sender. The raw trigger_description
     string is never logged (DEC-027 / SRS-202).
  5. On `response_code == 1` (cancelled) or `>= 2` (failure):
     publish `L0Focused` through the watch sender. The user can
     retry via the UI "Configure" button (gen2 Q6a).
  6. The worker enters a `tokio::select!` loop multiplexing the
     `cmd_rx` channel (Rebind / Stop) and the `Activated` /
     `Deactivated` signals. Matching signals scoped to this
     session handle and `chanora-ptt` shortcut id drive
     `gate.set(true/false)`.
  7. `Rebind` re-runs `BindShortcuts` on the same session.
  8. `Stop` calls `org.freedesktop.portal.Session.Close()` on
     the session-handle object path, clears the gate, exits.

UX (gen2 Q3a): when `_pttBackendId == 'gnome-wayland-portal'`,
the Flutter "Configure" button skips the in-app
`_PttBindingCaptureDialog` and shows a SnackBar telling the user
their desktop environment will open its own shortcut dialog.
The button delegates to `setPttBinding(keyboard, "portal")`
which nudges the backend; the portal handles the rest. New ARB
key `pttConfigurePortalRedirect` in en + zh-Hans.

Trait surface (cross-cutting):

  * `DesktopPttBackend::descriptor_watch()` is a new trait method
    with a default impl returning a never-firing receiver.
    Backends with async capability transitions (only the Linux
    portal backend today) override it to return the live watch
    sender's receiver.
  * `chanora_core::ChanoraSession::start_audio` subscribes to the
    active backend's `descriptor_watch()` and spawns a forwarder
    task that re-emits `SessionEvent::PttCapability` on every
    transition. The initial value is emitted synchronously.

`Cargo.toml` (Linux-only):

  * `futures-util` (std features, no executor) for stream
    consumption on the portal signal subscriptions.
  * `rand 0.8` for fresh per-process portal tokens.
  * `zbus` continues at v5 with the `tokio` + `blocking-api`
    features.

Tests
-----

  * `chanora_audio` rises from 8 to 18 unit tests. New
    coverage on the Linux module:
      - `classify_returns_none_when_shortcut_id_missing`
      - `classify_returns_keyboard_for_typical_trigger_description`
      - `classify_returns_keyboard_when_trigger_description_missing`
      - `classify_detects_mouse_substring`
      - `classify_is_case_insensitive_on_mouse_substring`
      - `publish_bound_keyboard_publishes_L2_with_keyboard_class`
      - `publish_bound_mouse_publishes_L3`
      - `publish_bound_none_publishes_L2_keyboard_default`
      - `publish_l0_clears_descriptor`
      - `shortcut_id_is_stable`
  * Workspace total: 67 unit + integration tests, all green with
    `CHANORA_DISABLE_KEYRING=1` (was 57 at v1.0.0-rc.4).
  * New `crates/chanora_audio/tests/linux_portal_smoke.rs`
    ignored integration test (RR-PTT-004 evidence path). Run on
    a GNOME-on-Wayland host with
    `cargo test -p chanora_audio --test linux_portal_smoke -- --ignored --nocapture`.

Documentation
-------------

  * `docs/architecture/desktop-ptt-architecture.md` §5.3 rewritten
    to describe the realised lifecycle; v0.9.4 change-history
    entry added.
  * `docs/governance/product-decision-register.md` v0.9.10
    change-history entry recording the code-side promotion. No
    decision rows mutate.
  * `docs/release/release-readiness-go-nogo-record.md` RR-PTT-004
    flipped from `Open` to `Implemented (live trace pending)`;
    v0.9.5 change-history entry.

Verification
------------

  * `cargo test --workspace`: 67/67 green.
  * `cargo deny check`: advisories ok, bans ok, licenses ok,
    sources ok.
  * `cargo about generate --offline`: zero new warnings.
  * `tools/dump_flutter_licenses.sh`: 94 packages, 0 without
    LICENSE.
  * `flutter analyze`: clean.
  * `cargo build -p chanora_bridge --release` +
    `flutter build linux --release`: clean Linux x86_64 bundle.
  * Live portal trace (RR-PTT-004) — **not run**. The dev shell
    is a TTY without a Wayland session. The user will run the
    ignored smoke test from inside a GNOME-on-Wayland session
    when available.

No Windows / macOS / iOS live verification in this commit (hosts
unavailable). The Windows + macOS backend scaffolds remain in
place reporting their target capability honestly; live OS-call
wiring is queued for their respective platform owners'
reference hosts per `docs/governance/staged-release-plan.md`.
2026-05-15 16:43:45 +08:00

235 lines
13 KiB
Markdown
Raw Blame History

# CHANORA_REL_Release_Readiness_Go_NoGo_Record_v0.9.2.2.1
**Document type:** Release Readiness Checklist / Go-No-Go Record
**Version:** 0.9.2
**Status:** Baseline Candidate
**Language:** English
**Product:** Chanora
**Repo path:** `docs/release/release-readiness-go-nogo-record.md` ---
## 1. Purpose
This document records the auditable release readiness decision for a Chanora release.
Design documents alone do not authorize release. A release requires an explicit readiness decision based on scope, build identity, requirement completion, verification evidence, security review, platform readiness, legal/privacy readiness, known risks, and approval.
## 2. Release Identity
| Field | Value |
|---|---|
| Release name | TBD by Product Owner |
| Release type | TBD: Internal Alpha / External Beta / MVP Public / Store Release |
| Release version | TBD |
| Release candidate ID | TBD |
| Release date target | TBD |
| Release owner | TBD |
| Product owner | TBD |
| Engineering owner | TBD |
| QA / verification owner | TBD |
| Security reviewer | TBD |
| Legal / compliance reviewer | TBD |
## 3. Build Identity
| Field | Value |
|---|---|
| Git repository | TBD |
| Git branch | TBD |
| Git commit SHA | TBD |
| Git tag | TBD |
| iOS App Store Connect upload SDK gate | Xcode 26+ and iOS 26 / iPadOS 26 SDK+ for upload on or after 2026-04-28 |
| Platform release policy included | Yes |
| Build number | TBD |
| CI pipeline ID | TBD |
| Build timestamp | TBD |
| Windows artifact | TBD |
| macOS artifact | TBD |
| Linux artifact | TBD |
| Android artifact | TBD |
| iOS artifact | TBD |
| Artifact hash method | SHA-256 unless otherwise specified |
| Artifact hashes | TBD |
## 4. Scope Readiness
| Question | Answer | Evidence | Owner |
|---|---|---|---|
| Is this release scope defined? | TBD | Release scope statement | Product Owner |
| Is this release Internal Alpha, External Beta, MVP Public, or Store Release? | TBD | Release scope statement | Product Owner |
| Are included features listed? | TBD | Release notes / scope list | Product Owner |
| Are excluded/deferred features listed? | TBD | Deferred requirements list | Product Owner |
| Are target platforms listed? | TBD | Platform readiness table | Engineering Owner |
| Are known limitations documented? | TBD | Known issue register | Product Owner / QA |
## 5. Requirements Readiness
| Requirement group | Status | Evidence | Deferred items / waiver |
|---|---|---|---|
| P0 / MVP connection requirements | TBD | SRS/SWE.6 evidence | TBD |
| P0 / MVP channel and state requirements | TBD | SRS/SWE.6 evidence | TBD |
| P0 / MVP voice requirements | TBD | SRS/SWE.6 evidence | TBD |
| Audio processing requirements | TBD | SWE.4/SWE.5/SWE.6 evidence | TBD |
| Storage and secure storage requirements | TBD | SWE.4/SWE.5/SWE.6 evidence | TBD |
| Diagnostics and redaction requirements | TBD | SWE.4/SWE.5/SWE.6 evidence | TBD |
| Material 3 / UI requirements | TBD | SWE.6 evidence | TBD |
| Accessibility requirements | TBD | SWE.6 evidence | TBD |
| Platform behavior requirements | TBD | SYS.4/SWE.6 evidence | TBD |
| i18n / Unicode requirements | TBD | SWE.4/SWE.5/SWE.6 evidence | TBD |
| Traceability requirements | TBD | Validation report | TBD |
## 6. Verification Readiness
| Verification layer | Required evidence | Status | Failed items | Waivers |
|---|---|---|---|---|
| SWE.4 Unit Verification | Unit verification summary report | TBD | TBD | TBD |
| SWE.5 Software Integration Verification | Integration verification summary report | TBD | TBD | TBD |
| SWE.6 Software Verification | Software verification summary report | TBD | TBD | TBD |
| SYS.4 System Integration Verification | System integration verification summary report | TBD | TBD | TBD |
| Regression Verification | Regression report | TBD | TBD | TBD |
| Manual exploratory test | Test notes | TBD | TBD | TBD |
## 7. Security Readiness
| Question | Required answer | Status | Evidence |
|---|---|---|---|
| Is secure storage verified for supported platforms? | Yes / waived | TBD | Security test report |
| Are secrets excluded from plaintext logs? | Yes / waived | TBD | Redaction test result |
| Is diagnostic export redaction verified? | Yes / waived | TBD | Diagnostics audit |
| Is dependency/license scan completed? | Yes / waived | TBD | Dependency scan report |
| Are high/critical dependency issues resolved or waived? | Yes / waived | TBD | Security waiver record |
| Are user-facing errors safe and non-sensitive? | Yes / waived | TBD | Review record |
| Are platform permissions justified? | Yes / waived | TBD | Permission review |
## 8. Platform Readiness
| Platform | Release status | Build artifact | Verification status | Known blockers | Owner |
|---|---|---|---|---|---|
| Windows | TBD: Go / Conditional Go / No-Go / Not in scope | TBD | TBD | TBD | TBD |
| macOS | TBD: Go / Conditional Go / No-Go / Not in scope | TBD | TBD | TBD | TBD |
| Linux | TBD: Go / Conditional Go / No-Go / Not in scope | TBD | TBD | TBD | TBD |
| Android | TBD: Go / Conditional Go / No-Go / Not in scope | TBD | TBD | TBD | TBD |
| iOS | TBD: Go / Conditional Go / No-Go / Not in scope | TBD | TBD, including Apple App Store SDK gate | TBD | TBD |
## 9. Legal, OSS, and Privacy Readiness
| Question | Required answer | Status | Evidence | Owner |
|---|---|---|---|---|
| Is the app clearly identified as unofficial and not affiliated with TeamSpeak? | Yes | TBD | App copy / legal notice | Legal |
| Is the TeamSpeak trademark/non-affiliation wording reviewed? | Yes | TBD | Legal review record | Legal |
| Is OSS license review completed? | Yes | TBD | OSS notice / license report | Legal / Engineering |
| Are Rust, Flutter, tsclientlib, and platform dependencies included in OSS review? | Yes | TBD | OSS license report | Legal / Engineering |
| Is privacy policy completed for the release scope? | Yes | TBD | Privacy policy URL/file | Legal |
| Are diagnostics/logging disclosures complete? | Yes | TBD | Privacy policy / in-app notice | Legal / Product |
| Are App Store / Play Store metadata requirements complete if applicable? | Yes / N/A | TBD | Store metadata review | Product / Legal |
## 10. Known Issues and Waivers
| Issue ID | Description | Severity | Impact | Waiver? | Waiver owner | Expiry / follow-up |
|---|---|---|---|---|---|---|
| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
## 10A. Required Security, Privacy, and Legal Evidence
| Evidence document | Required status before External Beta / Public release |
|---|---|
| `CHANORA_SEC_Threat_Model_v0.9.2.2.1.md` | Reviewed; v1.0 approved before public release |
| `CHANORA_SEC_Secure_Storage_Audit_Report_v0.9.2.2.1.md` | Completed for release-scope platforms |
| `CHANORA_SEC_Diagnostic_Redaction_Audit_Report_v0.9.2.2.1.md` | Completed and approved |
| `CHANORA_SEC_Dependency_And_Supply_Chain_Report_v0.9.2.2.1.md` | Completed with no unapproved critical/high risk |
| `CHANORA_PRIV_Privacy_Policy_v0.9.2.2.1.md` | Legal/privacy reviewed; v1.0 approved before public release |
| `CHANORA_LEGAL_Trademark_And_Attribution_Review_v0.9.2.2.1.md` | Legal reviewed; v1.0 approved before public release |
## 10B. Key Product Decision Gate
| Decision | Required status before Go |
|---|---|
| Release type | Confirmed |
| Release platform scope | Confirmed |
| Minimum iOS version | Confirmed |
| Apple App Store SDK gate | Confirmed and release-inspected |
| Minimum Android version | Confirmed |
| Android target SDK policy | Confirmed |
| Multiple active connections in MVP | Confirmed |
| AEC/AGC/NS/HPF default states | Confirmed |
| Audio processing implementation path | Confirmed |
| Legal/trademark/licensing review requirement | Confirmed |
| Local database choice | Confirmed |
| Flutter/Rust bridge choice | Confirmed |
| Diagnostics upload policy | Confirmed |
| Crash reporting policy | Confirmed |
| Product license model | Confirmed or explicitly not required for release scope |
## 11. Release Decision
| Decision | Meaning |
|---|---|
| Go | Release is approved for the stated scope and platforms. |
| Conditional Go | Release is approved only if listed conditions are satisfied. |
| No-Go | Release is not approved. |
**Decision:** TBD: Go / Conditional Go / No-Go
## 12. Conditional Go Conditions
| Condition ID | Condition | Owner | Due date | Evidence required |
|---|---|---|---|---|
| TBD | TBD | TBD | TBD | TBD |
## 13. Approval
| Role | Name | Decision | Date | Evidence / Signature |
|---|---|---|---|---|
| Product Owner | TBD | TBD | TBD | TBD |
| Engineering Owner | TBD | TBD | TBD | TBD |
| QA / Verification Owner | TBD | TBD | TBD | TBD |
| Security Reviewer | TBD | TBD | TBD | TBD |
| Legal / Compliance Reviewer | TBD | TBD | TBD | TBD |
| Release Manager | TBD | TBD | TBD | TBD |
## 14. Change History
| Version | Date | Description |
|---|---|---|
| 0.9.0 | 2026-05-14 | Initial release readiness and Go/No-Go record template. |
## Baseline Candidate 0.9.1 Update
| Version | Date | Description |
|---|---|---|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |
## Baseline Candidate 0.9.2 Update
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
## Desktop Push-to-Talk Release Readiness Addendum (Baseline Candidate 0.9.3)
The release readiness checklist for every desktop release artefact gains the following items per SysDes-148, SysRS-298, and DEC-023 / DEC-024 / DEC-025 / DEC-026 / DEC-027 / DEC-028.
| Item | Owner | Evidence required | Status |
|---|---|---|---|
| RR-PTT-001 Windows Global PTT verified on a Windows reference host. | Windows Platform Owner | Live measurement of `PttCapabilityLevel` + `backend_id` returned at runtime. Backend identifier shall be `raw-input` (preferred) or `low-level-hook` (fallback) for Global. | Open |
| RR-PTT-002 macOS Global PTT verified with permission granted on a macOS reference host. | macOS Platform Owner | Live measurement + `permission_state = Granted` reported through the Event-Tap backend; UI capability badge screenshot. | Open |
| RR-PTT-003 macOS Focused PTT fallback verified with permission denied. | macOS Platform Owner | Live measurement of `PttCapabilityLevel::L0Focused` after revoking Input Monitoring; UI capability badge screenshot showing the fallback notice. | Open |
| RR-PTT-004 Linux Global PTT verified on GNOME-on-Wayland. | Linux Platform Owner | Live measurement returning `gnome-wayland-portal` backend identifier from a live GNOME-on-Wayland host; portal binding dialog screenshot. | **Implemented** (live `CreateSession` + `BindShortcuts` + signal subscription landed in code; awaiting live trace from a GNOME-on-Wayland reference host before the cell can be marked Done). |
| RR-PTT-005 Linux Focused fallback verified on a non-tested compositor (any of: X11, sway, KDE) | Linux Platform Owner | Live measurement of `L0Focused` on at least one non-tested compositor; release notes do not claim Global support on the untested environment. | Open |
| RR-PTT-006 Diagnostic export carries no key data. | Privacy Reviewer | Inspection of a user-initiated diagnostic export captured while PTT is bound to a real key; export shall contain `capability_level`, `backend_id`, `bound_input_class` and shall not contain a recognisable key code. | Open |
| RR-PTT-007 Missed-key-up watchdog timeout demonstrated. | Audio Owner | Test trace showing `transmit_active` clearing after the configured 30 s ceiling when the watchdog forces a release. | **Done (v1.0.0-rc.4)** — covered by `chanora_audio::ptt::tests::watchdog_clears_transmit_after_timeout` (and the negative `watchdog_does_not_clear_on_normal_release`). Live platform trace still required per RR-PTT-001..005. |
| RR-PTT-008 Capability badge matches runtime capability on every supported platform. | UX Owner | UI screenshot or platform-test trace. | Open |
A release decision shall be **No-Go** for any platform whose RR-PTT items are not all closed.
| Version | Date | Description |
|---|---|---|
| 0.9.3 | 2026-05-15 | Added desktop PTT release-readiness items RR-PTT-001 through RR-PTT-008 covering Windows / macOS / Linux Global verification, permission-denied fallback verification, diagnostic-export privacy inspection, missed-key-up watchdog test, and capability-badge UI verification. |
| 0.9.4 | 2026-05-15 | RR-PTT-007 (missed-key-up watchdog) flipped to Done — the cross-platform `chanora_audio::ptt::MissedKeyUpWatchdog` ships in v1.0.0-rc.4 with two passing unit tests. Live per-platform traces (RR-PTT-001..005, RR-PTT-008) remain required for the live verification phase but are no longer blocked on engineering. |
| 0.9.5 | 2026-05-15 | RR-PTT-004 status flipped to Implemented (live trace from a GNOME-on-Wayland reference host pending). The Linux backend now runs the full portal `CreateSession` + `BindShortcuts` + `Activated` / `Deactivated` flow on a dedicated tokio task per backend instance. |
Reference in New Issue View Git Blame Copy Permalink