From 883fe6bee9253abbc4977a668c8c5b58b0e83783 Mon Sep 17 00:00:00 2001 From: Guillaume ETHEVE Date: Fri, 6 Nov 2026 04:35:20 +0100 Subject: [PATCH] docs: document independent feature PRs and combined builds --- docs/branches.md | 41 ++++++++++++++++++++++ docs/validation-all-features.md | 46 +++++++++++++++++++++++++ docs/validation-device-preferences.md | 49 +++++++++++++++++++++++++++ 3 files changed, 136 insertions(+) create mode 100644 docs/branches.md create mode 100644 docs/validation-all-features.md create mode 100644 docs/validation-device-preferences.md diff --git a/docs/branches.md b/docs/branches.md new file mode 100644 index 00000000..13d697ca --- /dev/null +++ b/docs/branches.md @@ -0,0 +1,41 @@ +# Branches and pull requests + +`main` mirrors `jimrandomh/faceclaw` at `6df52021c8e6c8fd843bc8d5652851e8c0fc6ab8`. It tracks `upstream/main`; Gitea is the push remote `origin` and uses `main` as its default branch. + +Each feature branch has one commit on this main, without unrelated features or environment setup. All PRs target `main`. + +| Group | Branch | PR | Independent JS tests | +| --- | --- | --- | --- | +| build: reproducible Nix environment for Android and Wear OS | `build/nix-android` | [#1](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/1) | 1061 passed, 2 skipped | +| fix: align the llama native library for Android 16 KiB pages | `fix/android-16k-pages` | [#2](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/2) | 1061 passed, 2 skipped | +| feat: configurable notification defaults and bulk actions | `feat/notifications` | [#3](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/3) | 1067 passed, 2 skipped | +| feat: share Android calendar selection across calendar readers | `feat/calendar-selection` | [#4](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/4) | 1065 passed, 2 skipped | +| feat: configure head-up wake and wake angle | `feat/head-up-wake` | [#5](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/5) | 1063 passed, 2 skipped | +| feat: system menu controls for app closing, full screen and keep awake | `feat/app-controls` | [#6](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/6) | 1076 passed, 2 skipped | +| feat: language selection for OpenAI and on-device Whisper | `feat/whisper-languages` | [#7](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/7) | 1067 passed, 2 skipped | + +All independent branches also passed `tsc --noEmit`. The head-up branch received a final import-only cleanup and was typechecked/linted again. + +`build/all-features` merges the seven feature branches and retains the combined validation records. It is the branch for APK builds, not a feature PR. Develop a change on its feature branch, then merge it into the build branch; do not merge the build branch back into a feature branch. + +## Cleanup archive + +The tag `archive/before-pr-cleanup-2026-11-06` preserves the complete previous integration history. Replaced branch tips are recorded below; no original feature implementation was discarded. + +| Previous branch | Archived commit | +| --- | --- | +| `build/wearos-release` | `2b14ea38b468241ebb5c4d3c0808e6df977ed93a` | +| `chore/nix-build-fixes` | `096510f5adef7c5ed369a89bcca9a1b8144dc51e` | +| `chore/nix-devenv` | `19cf564251507617982cd1ed1da66de317b38ff0` | +| `feat/app-fullscreen` | `49099d5efe6f32f91e0147b81cd613b2043d3378` | +| `feat/app-switcher-close-menu` | `be939f401bdb1372b0f6c9faef754d7a10ff4118` | +| `feat/notification-filter-default` | `5b3a4fa7475664733ca1dbed5d532347bf57c1a6` | +| `integration/device-preferences` | `1d230a401471b99d6136f27916dd90e98033ea26` | +| `fix/android-16k-pages` before squashing/rebase | `68c9dc7ae997c17327433e5b6481e64d6fecca9f` | +| `feat/calendar-selection` before squashing/rebase | `6397928c60fd227fae1d50532933fa390e415ff8` | +| `feat/head-up-wake` before squashing/rebase | `398c62af9adc1401fd3f5d96a5332dab693619bf` | +| `feat/whisper-languages` before squashing/rebase | `c5b57e85b0759bac594a50d9dc870fa1b26d155b` | + +The three Nix/build branches were consolidated into `build/nix-android`. The switcher-close and full-screen branches were consolidated into `feat/app-controls`. Notification defaults and dismissal remain together in `feat/notifications`. + +Hardware validation remains separate from software checks. No firmware was flashed during this cleanup. diff --git a/docs/validation-all-features.md b/docs/validation-all-features.md new file mode 100644 index 00000000..11782fcc --- /dev/null +++ b/docs/validation-all-features.md @@ -0,0 +1,46 @@ +# Combined release build + +Branch: `build/all-features`, based on the original GitHub main `6df52021c8e6c8fd843bc8d5652851e8c0fc6ab8`. +The seven independent feature PRs and archive mapping are listed in +[branches.md](branches.md). + +The build contains the Nix Android/Wear OS environment, Android 16 KiB native +alignment, notification defaults and bulk actions, shared Android calendar +selection, head-up wake/angle settings, application close/full-screen/independent +keep-awake controls, stock EvenHub canvas preservation, and multilingual Whisper. +It also retains the original main's Apple Watch additions. + +Validation after branch cleanup on 2026-11-06: + +- Every PR branch passed its independent JavaScript suite and TypeScript checks. +- Combined JavaScript suite: 1,094 passed, 2 skipped, 0 failed. +- Shared Kotlin Android host tests: 272 passed, 0 failures/errors. +- `tsc --noEmit` and lint on changed sources: passed. +- APK page-checker unit tests: 5 passed. All 7 phone native libraries pass + 16 KiB LOAD/RELRO checks; phone and Wear APK ZIP alignment passes. +- Android and Wear OS release builds: passed; `debuggable=false`, signatures + verified and identical to each other and the existing local installation key. +- Wear OS `lintRelease`: passed. Nix tool verification: passed. + +## Phone artifact + +`dist/faceclaw-all-features-release.apk` (95,272,100 bytes). +SHA-256, also saved beside the APK: + +```text +b3e416925ed55102044487d4a6b0bc97064c2fcf819860b25713f002d7d241c3 +``` + +## Wear OS artifact + +`dist/faceclaw-wear-release.apk` (2,861,168 bytes). +SHA-256, also saved beside the APK: + +```text +12782fbbb3fcdcf0700ef1a7019a1479b3bd144de1dba30dce806186a0a75366 +``` + +These locally signed builds were not installed during the branch cleanup. +Glasses validation remains pending; the per-feature validation documents describe +those checks. Static 16 KiB alignment does not establish execution on a real +16 KiB-page device. No firmware was flashed. diff --git a/docs/validation-device-preferences.md b/docs/validation-device-preferences.md new file mode 100644 index 00000000..6aa4b53d --- /dev/null +++ b/docs/validation-device-preferences.md @@ -0,0 +1,49 @@ +# Integrated device preferences + +Historical validation of the initial combined device-preferences build, preserved in `archive/before-pr-cleanup-2026-11-06`. Current branches and PRs are listed in [branches.md](branches.md); the combined build is now `build/all-features`. + +Software validation on Linux/NixOS, 2026-11-06: + +- JavaScript/TypeScript suite: 1,059 passed, 3 skipped, 0 failed. +- Shared Kotlin Android host suite: 269 passed, 0 failures/errors. +- TypeScript: `tsc --noEmit` passes. +- oxlint: passes with existing warnings outside the changes. +- Nix tools: Node 22, Java 21, Android SDK 35, both build-tools versions, + adb, host CMake/Ninja and NDK verified. Tested using devenv 2.4.0. + +Reproduce with `devenv shell`, then: + +```sh +npm ci +npm test +npm run test:kotlin +npx tsc --noEmit +bash lint.sh +bash scripts/check-devenv.sh +bash build.sh +``` + +The build produces a debug APK for arm64 Android phones. It does not install +the APK or flash firmware. Build output and machine-local signing/SDK files +are ignored by Git. + +Final artifact: `dist/faceclaw-device-preferences-debug.apk` (115,876,494 bytes), +package `com.faceclaw.app`, version 0.8.6 (806). Build completed successfully; +APK v2 signature verified with `apksigner`. The packaged JavaScript contains all +three controls, and the DEX contains the new calendar and head-up native APIs. +SHA-256 (also saved alongside the APK): + +```text +091ced145d499ec00aa03cbea60f5cec7a2167e459896c4b5b45211e1c9a7e8a +``` + +The updated APK also passes ELF LOAD/RELRO and ZIP alignment checks for 16 KiB +pages; see [16 KiB validation](validation-android-16k.md). + +Glasses validation remains pending. The APK was installed on a Pixel 10 Pro Fold, +which currently reports 4096-byte pages. No glasses were used. See the +manual procedures for [notifications](validation-notifications.md), +[Android calendars](validation-calendars.md) and [head-up wake](validation-head-up.md). +In particular, successful BLE encoding and simulated ACK/reconnect tests do +not establish physical wake/angle behavior on a target Faceclaw firmware. +The iOS calendar-selection port is deferred.