Skip to content

Commit 88b7871

Browse files
committed
[docs] prepare recovery release artifacts and channel handoff
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent e54a78a commit 88b7871

3 files changed

Lines changed: 243 additions & 0 deletions

File tree

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
<!-- SPDX-License-Identifier: MIT -->
2+
<!-- Part of PyBLE (https://pyble.dev) — see /LICENSE. -->
3+
4+
# App 0.3.0 (9) — release readiness and channel handoff
5+
6+
| Field | Record |
7+
|---|---|
8+
| Date | 31 October 2026, Asia/Bangkok |
9+
| Scope | App-only bounded current-text recovery; existing Play open-testing and TestFlight channels |
10+
| Source | Merged PR #40 at `6f5b3ea73a70342331fb49d0685938ce2a4cae11`; app tree `b12fe3621f1d100a3b3724d15ee0dea3b359acfe` |
11+
| State | Production Android and iOS packaging verified for this source; physical acceptance and final release admission remain outstanding. The physical-device follow-up identified a keyboard-layout issue being repaired separately, so these pre-fix artifacts are provisional and must be rebuilt after that change |
12+
| Local evidence | Ignored `local/recovery-completion/release/`: build/check logs, artifact manifest and retained signed binaries |
13+
| Public copy | [Prepared release packet](../../../publication/app-0.3.0-build-9-release-packet.md); no submission or availability claim |
14+
15+
## Gate selection
16+
17+
This increment changes the app, not the firmware bytes. The
18+
[qualification inventory](../c1-s1/04_Validation_Inventory_and_Operator_Recipe.md#1-evidence-and-gate-selection)
19+
requires affected app workflows on the five existing exact profiles and both
20+
platforms for that compatibility claim. An unchanged firmware is a named input
21+
with its own historical qualification limits. This work does not require or
22+
claim a new firmware release, fresh firmware OI-1 qualification or a Ready badge.
23+
24+
| Gate | Required evidence | Current disposition |
25+
|---|---|---|
26+
| M-02 recovery acceptance | All DR-T01–14 required evidence, including representative physical generated-text recovery and both platform offline/current-board-consent records | Reconcile against the [execution record](00_Execution_Record.md) and actual device reports; installation/scan alone is insufficient |
27+
| App regression | Accepted source contract, red/green history, locked dependencies, ordinary tests, pinned goldens, platform builds and repository gates | PR #40 and its post-merge CI passed; 972 ordinary Flutter tests recorded; rerun affected checks for any further code change |
28+
| Five-profile app compatibility | Q01–Q10 below with exact app/firmware identity, actual observations and retained failures | Final complete candidate-bound matrix not yet established |
29+
| Production packaging | Android upload signer/AAB/APK/native alignment; iOS distribution export/IPA validation; capability parity | Android and iOS checks below pass for the recorded source; affected checks must follow a repaired candidate |
30+
| Release review | Frozen artifact identity, resolved mandatory failures, supported scope, privacy/dependency review and recorded acceptance | Not yet admitted |
31+
| M-05 channel delivery | Actual upload/processing/review/availability, followed by store-delivered installed identity and upgrade/launch checks | No upload or new channel delivery established by this preparation |
32+
33+
Pilot participation and useful-return evidence remain separate from maintenance
34+
release admission. A second operator is required for the optional reproduction
35+
claim, not for an unrelated app release. Neither distinction waives mandatory
36+
physical or packaging evidence.
37+
38+
## Required app compatibility rows
39+
40+
| iPad row | Android row | Exact profile | App checks |
41+
|---|---|---|---|
42+
| Q01 | Q02 | `esp32-4mb` | Common workflow plus affected recovery |
43+
| Q03 | Q04 | `esp32-s3-n16r8` | Common workflow plus affected recovery; do not infer the profile from the `esp32-s3` chip string alone |
44+
| Q05 | Q06 | `waveshare-esp32-s3-lcd-147b` | Common workflow plus affected recovery; keep its exact-board/image identity distinct from generic S3 |
45+
| Q07 | Q08 | `esp32-c3-4mb` | Common workflow plus affected recovery and the real-app C3-G5 behavior |
46+
| Q09 | Q10 | `rpi-pico2-w` | Common workflow plus affected recovery on each physical platform; no new full GP2 qualification inferred |
47+
48+
Each common row includes ordinary service-filtered discovery/HELLO, editing and
49+
saving a harmless file, Run/stdout/terminal state, Stop, exact file readback,
50+
disconnect/reconnect and workspace continuity. Retain the selected candidate's
51+
affected lifecycle/recovery scenarios. Record the actual result of every row;
52+
a scan result or one platform cannot stand in for another row.
53+
54+
[C3-G5](../../../specifications/firmware/ports/esp32-c3-4mb.md#c3-g5--real-app-hil-on-both-platforms-frozen)
55+
requires Stop through the real UI against both a tight loop and print flood.
56+
Its C3-G2 oracle is exactly one matching `RSP{OK}` before `RUN_STATE(idle)` in
57+
less than 500 ms from complete STOP submission, a usable connection, and a
58+
subsequent bounded run. UI responsiveness alone cannot establish that wire
59+
latency. There is no new arbitrary repetition count added by this app increment.
60+
61+
## Prepared Android production artifacts
62+
63+
Both builds use normal `lib/main.dart`, production flavor and the established
64+
owner upload key. Secret values were obtained from the existing local secret
65+
manager and never written into source or logs.
66+
67+
| Artifact | SHA-256 | Bytes |
68+
|---|---|---:|
69+
| `PyBLE-0.3.0-build-9-production-release.aab` | `fcf4692dbf7655f53a50a0687eedb81d9cf63bc601721552f622246d5cca0330` | 64,414,627 |
70+
| `PyBLE-0.3.0-build-9-production-release.apk` | `8656549a8480ae7ebfe9b6023220fa35c9b967fb07ca0a754a0ec24cd63e3e13` | 66,439,954 |
71+
72+
| Check | Actual result |
73+
|---|---|
74+
| Package and version | `dev.pyble.pyble`, `0.3.0`, version code `9` |
75+
| SDKs / ABIs | Minimum 24, target/compile 36; `arm64-v8a`, `armeabi-v7a`, `x86_64` |
76+
| Signing | AAB JAR verification and APK signature verification pass; certificate SHA-256 matches the retained owner certificate `DCA95C5060CDF4936F19FD8C3212A871C223E2BA3FB67B6226179AFFDA62DD57` |
77+
| Bundle | Official bundletool 1.18.3 validation passes; tool digest checked against the retained verified digest; configuration declares `PAGE_ALIGNMENT_16K` |
78+
| Native libraries | All 12 packaged shared objects have every ELF LOAD alignment at least 16 KiB, including `libsqlite3.so` and `libdartjni.so` on all three ABIs |
79+
| APK alignment | `zipalign -c -P 16 -v 4` passes |
80+
| Permissions | Expected BLE, legacy location, Internet and AndroidX signature permission; no new authored platform permission |
81+
| Runtime page-size check | Production APK launched on the official API 36 Google APIs 16 KiB arm64 emulator; kernel `PAGE_SIZE=16384`, About `Version 0.3.0 (9)`, bundled native SQLite mapped from the APK, and fresh schema v1 created successfully |
82+
83+
The 16 KiB runtime observation also force-stopped and relaunched the same
84+
installed package without data clearing. The normal disconnected screen
85+
returned; the retained fresh database and WAL reopened with `integrity_check=ok`
86+
and the expected `projects`, `project_files` and `settings` tables. This is a
87+
native packaging/startup smoke, not a physical BLE row or the full recovery
88+
acceptance matrix. The SQLite database's own page size is independent of the
89+
operating-system memory page size.
90+
91+
The first local invocation incorrectly used `--no-pub` after fresh `pub get`,
92+
leaving the integration-test plugin in a generated Android registrant. Its
93+
failed log is retained. Repeating the canonical CI production commands,
94+
which allow Flutter to regenerate release plugin metadata, built both artifacts
95+
successfully without a source change.
96+
97+
The APK uses the upload certificate, whereas Google Play can deliver its own
98+
app-signing certificate. Do not uninstall an existing user's Play app or clear
99+
its data merely to install this locally signed APK. Store upgrade acceptance
100+
must use the actual delivered package.
101+
102+
## Prepared iOS distribution artifact
103+
104+
| Field / check | Actual result |
105+
|---|---|
106+
| IPA | `PyBLE-0.3.0-build-9-app-store.ipa`, 23,782,489 bytes |
107+
| SHA-256 | `73ad7cda10c402a7f25316efc5e30f9c80bbd030e23c2bfc32313fd79c41c2ab` |
108+
| Identity | `dev.pyble.pyble`, `0.3.0 (9)`, normal `lib/main.dart` |
109+
| Build / deployment floor | Xcode 27.2 / iOS SDK 27.2; app and compiled deployment floor at least iOS 15.0 |
110+
| Export | App Store Connect distribution export; automatic signing with build-number management disabled; export destination only, no upload |
111+
| Provisioning | Production App Store profile; debugging disabled, no development-device list, beta reporting enabled; valid through 17 May 2027 |
112+
| Validation | `tools/validate_ios_ipa.sh` passes code-signature, compiled minimum OS, embedded-asset mode/classification and Xcode `swinfo` checks; only the three expected unsigned resource-bundle records are excluded |
113+
114+
The archive and exported IPA are retained privately. A distribution package
115+
with no development-device list is not the separately installed development
116+
Preview app. Its local validation does not establish App Store processing,
117+
TestFlight availability, or store-installed upgrade behavior.
118+
119+
## Distribution access and remaining account work
120+
121+
The owner Android upload identity is locally usable and matches the historical
122+
certificate. A valid Apple distribution identity and cached production App
123+
Store provisioning profile are available. Signing access alone does not prove
124+
an authenticated store session, role, account version history or review status.
125+
126+
No dedicated Play/App Store Connect connector or configured command-line store
127+
credential was found in the standard locations inspected. Account access and
128+
whether build 9 has already been consumed remain **unverified**. This is not a
129+
claim that the owner has no access through the respective web consoles.
130+
131+
After the candidate is admitted, the authorized distribution operator must
132+
verify the exact package, unused build numbers and current declarations, upload
133+
the retained artifacts, resolve processing/review findings, and record actual
134+
availability and installed-store results separately. The prepared packet and
135+
artifact records make those steps concrete; they do not substitute for them.
Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<!-- SPDX-License-Identifier: MIT -->
2+
<!-- Part of PyBLE (https://pyble.dev) — see /LICENSE. -->
3+
4+
# PyBLE 0.3.0 (9) — prepared app release packet
5+
6+
Prepared 31 October 2026. This is candidate copy for the existing Google Play
7+
open-testing and TestFlight channels. It does not announce availability, a
8+
submission, or release admission. The [readiness record](../developments/2026-q4-reliable-workflow/c1-s2/06_Release_Readiness.md)
9+
owns the artifact and gate states. Confirm that build 9 is unused in each
10+
account before uploading; a consumed number requires a new source version
11+
contract and rebuilt artifacts, not a renamed file.
12+
13+
## Google Play release notes
14+
15+
```text
16+
PyBLE can now keep one current Python draft locally and offer Restore or Discard after an app restart. Local recovery status is shown separately from saving to a board. Recovered text requires confirmation of the current destination before board Save, Run or Upload. Blocks workspaces and multi-file projects are not included in local draft recovery. A compatible MicroPython board with the PyBLE agent is still required for board workflows.
17+
```
18+
19+
## TestFlight — What to Test
20+
21+
```text
22+
Test local recovery of the current Python text draft in PyBLE 0.3.0 (9).
23+
24+
Use a compatible, separately provisioned MicroPython board running the PyBLE agent. Keep test hardware free of hazardous loads. About identifies the installed app version; record the board profile and agent version with feedback.
25+
26+
1. Edit a disposable Python draft, choose Save recovery copy, and wait for Saved locally. Close the app process and reopen it without deleting or reinstalling the app. Check the exact text and filename in the recovery preview.
27+
2. Restore while disconnected. Recovery should preserve the text without connecting to or writing to a board. Cancel a Discard confirmation, then confirm Discard using only disposable content; check the next launch.
28+
3. Deliberately connect to a board. Check the current destination and separate Save/Run effects before confirming. Cancel a confirmation and verify that no unwanted board action occurs.
29+
4. Copy generated Python from Blocks into Editor, save its recovery copy, and restart. Only the generated text is covered; the Blocks workspace, graph revisions and companion files are not restored by this local slot.
30+
5. Exercise New, Board Open, Files Upload, disconnect/reconnect, portrait/landscape, larger text, an external keyboard and VoiceOver where available. Report any lost text, stale destination, inaccessible control or inaccurate success message.
31+
32+
There is one recovery slot and no draft history. Wait for Saved locally before expecting an edit to survive termination. Storage failure can leave current edits only in memory; follow the displayed guidance. App removal or clearing app storage removes local recovery data. A draft that existed only in memory in an older version cannot be recovered by upgrading.
33+
34+
Include app version/build, tablet/OS, exact board profile and agent version, numbered steps, expected and actual behavior, and whether the event followed an app restart or board switch. Omit private source, device identifiers, credentials and personal data from public reports.
35+
```
36+
37+
Keep the existing maintained contact/review information and hardware-access
38+
instructions in the account. Verify them against the current form rather than
39+
inventing reviewer access, audience declarations, privacy attestation or a
40+
store review result. No tester invitation is sent by preparing this packet.
41+
42+
## Artifact and channel handoff
43+
44+
| Step | Required result |
45+
|---|---|
46+
| Candidate | Final accepted source/app tree, locked dependencies, exact signed artifact hashes, full `0.3.0 (9)` identity and retained checks |
47+
| Android package | `dev.pyble.pyble`, production flavor, normal `lib/main.dart`; existing owner upload signer, AAB validation and native alignment checks |
48+
| iOS package | `dev.pyble.pyble`, normal `lib/main.dart`, distribution export and successful `tools/validate_ios_ipa.sh` |
49+
| Admission | Accepted recovery evidence, required app/profile matrix, packaging/provenance review and no unresolved release-blocking defect |
50+
| Account checks | Unused build numbers; current upload/signing identity, account role, declarations, review contact and hardware instructions |
51+
| Submit | Upload only admitted artifacts; record processing and review outcomes independently on Play and App Store Connect |
52+
| Verify delivery | Record actual track/group availability, then store-delivered installation/upgrade, About identity and a scoped launch/workflow check |
53+
| Public copy | Update release availability only after observing it; preserve each platform's actual status |
54+
55+
The isolated development applications used for engineering tests have different
56+
application identities. Their successful installation does not prove an upgrade
57+
of `dev.pyble.pyble`, store processing, or store delivery. A distribution export
58+
also does not establish successful execution on the physical tablet.
59+
60+
## Privacy and recovery scope
61+
62+
Candidate 0.3.0 adds an app-private local database containing one current text
63+
draft and bounded recovery metadata. See the dated addendum in the
64+
[Data safety assessment](google-play-data-safety.md#31-october-2026--candidate-030-local-recovery-addendum).
65+
The slot has no app-managed cloud synchronization. OS backup behavior remains
66+
subject to platform and user settings. Board files and exported copies have
67+
their own retention boundaries; Discard does not delete them.
68+
69+
## Official submission references checked 31 October 2026
70+
71+
- Google requires new app/update submissions to target API 36 or higher under
72+
the current mobile-app rule: [target API requirements](https://support.google.com/googleplay/android-developer/answer/11926878).
73+
- Apps targeting Android 15 and higher must support 16 KiB pages on 64-bit
74+
devices: [Android page-size guidance](https://developer.android.com/guide/practices/page-sizes).
75+
- Apple accepts uploads through its supported tools with the appropriate
76+
account role; processing must finish before the build appears in App Store
77+
Connect: [upload builds](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds/).
78+
79+
These public requirements do not reveal this application's private account
80+
history or satisfy its project-specific hardware and release gates.

‎docs/publication/google-play-data-safety.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,34 @@ Console form. Reconcile it with the exact signed bundle, all active versions
66
covered by the package-level form, endpoint behavior and the final Console
77
questions before submission.
88

9+
## 31 October 2026 — candidate 0.3.0 local recovery addendum
10+
11+
The source candidate `0.3.0 (9)` adds a durable app-private `pyble.sqlite`
12+
database for one current Python text draft, its filename and bounded recovery
13+
metadata. This supersedes the **in-memory-only** editing description below for
14+
that candidate; the September table remains the historical `0.2.0` assessment.
15+
Blocks workspaces, multi-file projects and draft history are outside the local
16+
recovery slot. Restoring a draft does not itself send it to a board or network.
17+
18+
The local database adds no app-managed cloud synchronization, telemetry or
19+
developer collection endpoint. The existing app policy's local retention and
20+
platform-backup statements still apply: OS backup depends on the platform and
21+
user settings. Do not equate local-only app processing with a guarantee that
22+
the OS never backs up app storage. Confirm packaged backup settings when
23+
reviewing the final artifacts.
24+
25+
Explicit Discard removes the current recovery slot; it is not a secure-erasure
26+
promise for database pages, OS backups, exports or board files. Clearing app
27+
storage/uninstalling on Android or deleting the app on iPadOS removes the
28+
installed app's local data, subject to the separately described platform backup
29+
behavior. No pre-upgrade draft that existed only in memory can be recovered.
30+
31+
The board/GitHub flow analysis and proposed Console answers below still need
32+
owner review against the exact final bundle and all active versions. This
33+
addendum records a source change, not a submitted Data safety declaration.
34+
See the [prepared release packet](app-0.3.0-build-9-release-packet.md) for
35+
candidate-specific tester copy and the channel handoff.
36+
937
## Why the internal-testing answer needs review
1038

1139
The move to open testing requires a Data safety form. Google defines

0 commit comments

Comments
 (0)