|
| 1 | +<!-- SPDX-License-Identifier: MIT --> |
| 2 | + |
| 3 | +# Tutorial screenshot provenance — TEMPLATE |
| 4 | + |
| 5 | +Copy this template into the release review record. Raw captures and generated |
| 6 | +review candidates remain below the repository's ignored `ScreenShots/` |
| 7 | +workspace. Only an explicitly approved derivative may later be promoted to |
| 8 | +`tools/web/public/`. |
| 9 | + |
| 10 | +## Capture set |
| 11 | + |
| 12 | +- Capture date (UTC): `YYYY-MM-DD` |
| 13 | +- Reviewer and review date: `NAME — YYYY-MM-DD` |
| 14 | +- Physical device: `Lenovo TB-J616X` |
| 15 | +- Android release / API level: `Android 12 / API 31` |
| 16 | +- PyBLE version and build: `VERSION (BUILD)` |
| 17 | +- Installed package identity: `PACKAGE` |
| 18 | +- APK source commit and SHA-256: `COMMIT — SHA256` |
| 19 | +- Connected board and firmware: `BOARD — VERSION` |
| 20 | +- Raw directory (ignored): `ScreenShots/...` |
| 21 | +- Review directory (ignored): `ScreenShots/.../reviewed-tutorial-set` |
| 22 | +- ImageMagick version: output of `magick -version` |
| 23 | + |
| 24 | +## Deterministic processing |
| 25 | + |
| 26 | +Run from the repository root, using explicit absolute paths: |
| 27 | + |
| 28 | +```sh |
| 29 | +tools/web/scripts/process-tutorial-captures.sh \ |
| 30 | + --input-dir /ABSOLUTE/PATH/TO/RAW-CAPTURES \ |
| 31 | + --output-dir /ABSOLUTE/PATH/TO/RAW-CAPTURES/reviewed-tutorial-set |
| 32 | +``` |
| 33 | + |
| 34 | +The processor accepts exactly eight named 2000×1200, 8-bit PNG inputs. It |
| 35 | +crops 36 pixels from the top and 72 from the bottom, yielding 2000×1092. It |
| 36 | +then strips metadata and excludes time-dependent PNG chunks with fixed PNG |
| 37 | +compression settings. It does not resize, annotate, blur, recolor, or retouch |
| 38 | +app pixels. The command verifies every output against the exact source crop |
| 39 | +and writes `SHA256SUMS` plus `SOURCE_SHA256SUMS`. It also writes |
| 40 | +`tutorial-captures.tsv`, mapping each stable capture key to its raw file, |
| 41 | +content-versioned reviewed filename, and both full SHA-256 values. Reviewed |
| 42 | +filenames include the PyBLE app version, build, and first 12 hash characters. |
| 43 | + |
| 44 | +Use `--force` only after reviewing the current directory. It replaces only a |
| 45 | +directory containing the processor's managed filenames; any unmanaged entry |
| 46 | +causes a safe failure. Publication remains a separate, deliberate action. |
| 47 | +Preserve any older `reviewed/` directory as historical local evidence; this |
| 48 | +capture set belongs in the distinct `reviewed-tutorial-set/` directory. |
| 49 | + |
| 50 | +Verify the processor contract itself with: |
| 51 | + |
| 52 | +```sh |
| 53 | +tools/web/scripts/test-process-tutorial-captures.sh |
| 54 | +``` |
| 55 | + |
| 56 | +Verify an actual local set from its raw directory with: |
| 57 | + |
| 58 | +```sh |
| 59 | +capture_root=/ABSOLUTE/PATH/TO/RAW-CAPTURES |
| 60 | +review_dir="$capture_root/reviewed-tutorial-set" |
| 61 | +(cd "$review_dir" && shasum -a 256 -c SHA256SUMS) |
| 62 | +(cd "$capture_root" && \ |
| 63 | + shasum -a 256 -c "$review_dir/SOURCE_SHA256SUMS") |
| 64 | +``` |
| 65 | + |
| 66 | +## Per-image review |
| 67 | + |
| 68 | +| Tutorial / purpose | Raw filename | Reviewed filename | Raw SHA-256 | Reviewed SHA-256 | Visual state correct | Privacy review | Approved | |
| 69 | +| --- | --- | --- | --- | --- | --- | --- | --- | |
| 70 | +| Setup — board discovery | `06-setup-scan-results-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 71 | +| Setup — connected identity | `07-setup-connected-identity-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 72 | +| First program — editor and Console | `08-first-program-editor-console-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 73 | +| Files — multi-delete review | `09-files-multi-delete-review-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 74 | +| GitHub — branch chooser | `10-github-import-branch-chooser-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 75 | +| GitHub — pre-write review | `11-github-import-prewrite-review-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 76 | +| Examples — completed import | `12-examples-import-complete-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 77 | +| Blocks — generated Python | `20-blocks-hello-workspace-production-release.raw.png` | from manifest | `...` | `...` | `yes/no` | `pass/fail` | `yes/no` | |
| 78 | + |
| 79 | +Review each image at full resolution. Confirm that it contains no private |
| 80 | +notifications, account details, credentials, personal filenames, device |
| 81 | +identifiers beyond the intentionally documented test device/board, or debug or |
| 82 | +integration-test labels. Raw captures 06–12 contain the Lenovo stylus edge |
| 83 | +affordance; record it as disclosed, non-private device chrome and preserve it |
| 84 | +rather than retouching app pixels. Capture 20 is overlay-free. Confirm that |
| 85 | +captions and alt text describe the exact visible state before promotion. |
0 commit comments