From fc1cf589a7e4111d9250c0a5f5787caea4201664 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 6 Jul 2026 12:33:04 +0000 Subject: [PATCH] Document update release policy --- README.md | 37 +++++++++++++++++++++++++----------- docs/android-client-notes.md | 30 ++++++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 23bb193..977b418 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,17 @@ APIs directly: and kill session through HTTP API - open one live terminal viewer through `/ws/terminal` - native `/ws/events` listener for session invalidation and hook notifications -- GitHub and Gitea update manifest mirrors with fallback +- selectable GitHub or Gitea update manifest source - native API action center for health, server status, timeline, preferences, kanban projects, group messages, hook events, image file/URL upload, image preview info, and native image preview display - mobile soft-key row for tmux-oriented input, including tmux prefix, detach, new window, previous/next window, Ctrl keys, arrows, page keys, and paste -- automatic update checks against a GitHub Release manifest -- APK download, SHA-256 verification, and installer handoff +- automatic update checks against the selected release manifest +- one-download-per-version APK cache, SHA-256 verification, and installer + handoff +- native Update and About pages for version, protocol, permission, and release + information ## Server URL @@ -75,7 +78,12 @@ Create the base64 value from your release keystore: base64 -w 0 tmux-android-release.jks ``` -Publish a test build by pushing a `v*` tag. That creates a GitHub Release with: +Branch builds create Actions artifacts only. Use them to verify grouped changes +before publishing. + +Publish a release build by pushing a `v*` tag. A tag should be reserved for a +coherent feature/test batch, not every small UI or text change. Tag publishing +creates a GitHub Release with: ```text https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk @@ -143,8 +151,11 @@ The public manual APK download is: https://github.com/neatstudio/tmux-browser-android/releases/latest/download/tmux-android.apk ``` -The app tries the selected update source first, then falls back to the GitHub -manifest and the Gitea release API. The Gitea API endpoint is: +The app checks only the selected update source. It does not probe GitHub and +Gitea during the same update check. Choose the source in the app's `Update` +page, or use a custom manifest/API URL. + +The built-in Gitea API endpoint is: ```text https://gitea.neatcn.com/api/v1/repos/tmux/tmux-browser-android/releases/latest @@ -159,10 +170,14 @@ https://gitea.neatcn.com/tmux/tmux-browser-android/releases/download/v0.1.7/tmux In the app: -- Tap `Update` on the main screen to check `latest.json`, download the APK, - verify SHA-256, and open Android's installer. +- Open the `Update` page to check `latest.json`, download the APK, verify + SHA-256, and open Android's installer. +- If the same version APK was already downloaded and its SHA-256 still matches, + the app reuses that file instead of downloading it again. - Open `More` -> `Open APK download` to download the current public APK in a browser. -- Open `More` -> `Permissions / update status` to see the installed version, - update manifest, APK URL, install permission state, and a `Check update` - button. +- Open the `Update` page or `More` -> `Permissions / update status` to see the + installed version, selected update source, APK URL, install permission state, + and a `Check update` button. +- Open the `About` page to see the app version, package name, API/protocol + summary, and update policy. diff --git a/docs/android-client-notes.md b/docs/android-client-notes.md index aa4649e..fac90dd 100644 --- a/docs/android-client-notes.md +++ b/docs/android-client-notes.md @@ -70,6 +70,7 @@ Implemented now: - configurable base URL, defaulting to `http://100.89.0.116:3000` - support for Tailscale URLs such as `http://100.x.y.z:3000` +- native multi-page shell with `Sessions`, `Tools`, `Update`, and `About` - native session list from `GET /api/sessions` - create, rename, command send, split, pane select, pane kill, pin, mute, and kill session through documented session/preference endpoints @@ -83,7 +84,34 @@ Implemented now: metadata, and native image preview display - GitHub Actions APK build - release manifest `latest.json` -- APK download, SHA-256 verification, and installer handoff +- selected-source update checks; GitHub and Gitea are not probed in the same + update check +- one-download-per-version APK cache, SHA-256 verification, and installer + handoff +- permission/about surfaces for unknown-app install status, notification status, + app version, package name, and API/protocol summary + +## Update And Release Policy + +The Android app cannot silently replace itself. It may download a newer APK and +open Android's package installer, but the user must approve the install. On +Android 8+, the user may also need to allow this app to install unknown apps. + +The app checks exactly one update source per run: the selected manifest/API URL. +GitHub is the default public source. Gitea is available as a public mirror, but +the app does not fall back across both providers during a normal check. This +keeps update behavior predictable on mobile networks and avoids duplicate +provider checks. + +Downloaded APKs are cached by `versionCode`. If a cached APK exists and its +SHA-256 matches the manifest, the app reuses it instead of downloading the same +version again. This matters when Android redirects the user to unknown-app +install settings before the installer can run. + +Only `v*` tags publish GitHub Releases. Main branch builds are for CI artifacts +and should be used to validate grouped changes. Do not publish a new tag for +every small UI copy or layout change; publish when there is a useful feature or +test batch for phone-side validation. ## Native Roadmap