Merge branch 'mobile/docs' of github.com:Couchers-org/couchers into mobile/docs

Author: aapeliv

app/mobile/README.md

@@ -51,11 +51,11 @@ npm run start:devtool
 
 You should now see the mobile app on your phone.
 
-This setup will point at your local version of the React Native app, but it will point at the staging web app and backend. You probably want to follow the instructions on local dev below to run the full stack locally.
+This setup will point at your local version of the React Native app with the staging web app and backend. If you change any code within the web or backend folders, you will need to run the full stack locally to see your changes. Follow the instructions on local dev below.
 
 ## 2. Full local development setup
 
-To actually do full local development, you will want to run the entire stack on your dev machine, and point the dev tool at that instead of the staging environment.
+To run the mobile, frontend and backend environments fully locally, you need to run the entire stack on your dev machine, and point the dev tool at that instead of the staging environment.
 
 First, run the following script which patches environment variables to point the app at your local running versions of the frontend and backend. It auto-detects your IP and updates all config files at once:
 
@@ -69,12 +69,13 @@ Now run everything from the repo root, each in a separate terminal:
 
 ```bash
 # Terminal 1: backend (requires Docker)
+
 docker compose up --build
 
 # Terminal 2: web frontend
 cd app/web && yarn install && yarn start
 
-# Terminal 3: Expo
+# Terminal 3: Expo (Mobile)
 cd app/mobile && npm run start:devtool
 ```
 
@@ -180,7 +181,9 @@ All release builds (Dev Tool, Stage, Prod) are done in CI ([`app/.gitlab-ci.yml`
 
 Releasing to users is then a manual process:
 
-**Staging** builds are for internal testing and are available as soon as CI submits them (TestFlight after Apple's automated processing; Play internal testing immediately). Optionally add release notes in [App Store Connect](https://appstoreconnect.apple.com) (Couchers (Staging) → TestFlight → build → "What to Test") or the [Google Play Console](https://play.google.com/console) (Couchers (Staging) → Testing → Internal testing → release notes).
+**Staging** builds are for internal testing and are available as soon as CI submits them (TestFlight after Apple's automated processing; Play internal testing immediately). Ideally add release notes in [App Store Connect](https://appstoreconnect.apple.com) (Couchers (Staging) → TestFlight → build → "What to Test") or the [Google Play Console](https://play.google.com/console) (Couchers (Staging) → Testing → Internal testing → release notes) so testers know what to look for.
+
+Update `RELEASE_NOTES.md` as you code to keep track of changes then copy/paste this after building.
 
 **Production** releases should be coordinated with the team, after the changes have been tested in staging:
 

docs/native-dev-tool.md

@@ -1,6 +1,6 @@
 # Couchers Dev Tool
 
-The Couchers Dev Tool is a simple app that uses the Expo development client, along with OTA updates, to allow devs and non-devs to easily develop and QA the native app.
+The Couchers Dev Tool is a simple app that uses the Expo development client, along with OTA (over-the-air) updates, to allow devs and non-devs to easily develop and QA the native app.
 
 It supports:
 
@@ -14,7 +14,7 @@ The point is that you only need to do full builds if you're changing native modu
 * **iOS**: via TestFlight, ask a native dev lead to be added.
 * **Android**: download the APK from [the dev tool builds page](https://develop--devtool-builds.preview.couchershq.org/).
 
-It's a dev build, so we can't distribute it through the app stores proper. The Dev Tool coexists with the staging and production apps on the same device (it has its own bundle ID), and points at the staging backend by default.
+It's a dev build, so we can't distribute it through the app stores proper. The Dev Tool coexists with the staging and production apps on the same device (it has its own bundle ID), and points at the staging frontend (web) and backend by default.
 
 ## Workflow 1: local development
 

docs/native-ota-updates.md

@@ -42,7 +42,7 @@ When fingerprints change, we must publish a new version via app stores, and user
 
 ### On the client
 
-I keep saying OTA updates give us "flexibility", but not full control.
+OTA updates give us "flexibility", but not full control.
 
 In order to update the app, the app needs to download a signed bundle of Hermes compiled JavaScript code. It then needs to **restart the app** in order to apply that code update. In practice you want to always apply a new code bundle at startup, not interrupt a session. You could feasibly download the bundle on app load, then apply it immediately. The Expo default will try to download bundles in the background, then apply them the next moment the user puts the app away and/or restarts it in the foreground.
 
@@ -54,11 +54,11 @@ In order to find out about a new update, Expo uses the "Expo Updates Protocol v1
 
 Our backend serves the update protocol in `Bugs.GetNativeUpdateManifest`, which the client loads from `https://api.couchers.org/native/ota/manifest`. This endpoint decides which update to serve, depending on various logic.
 
-The backend generally picks the newest non-banned OTA update for the combination of platform and fingerprint available from teh database, then serves pre-signed manifest bytes that are fetched from the CDN. (Banning is a mechanism to quickly stop us from distributing botched updates.)
+The backend generally picks the newest non-banned OTA update for the combination of platform and fingerprint available from the database, then serves pre-signed manifest bytes that are fetched from the CDN. (Banning is a mechanism to quickly stop us from distributing botched updates.)
 
 ### Publishing new updates
 
-The publishing flow involes basically taking a full Expo bundle (generated via `ota-bundle.mjs`), stamping it with a new publish timestamp, signing it, producing a manifest file, and telling the backend about it.
+The publishing flow involves taking a full Expo bundle (generated via `ota-bundle.mjs`), stamping it with a new publish timestamp, signing it, producing a manifest file, and telling the backend about it.
 
 You can see how this works by tracing the staging OTA update flow (from `.gitlab-ci.yml`), where we build a new update on every push to `develop`. For prod the flow is the same, but we have a magic button in a magic place to trigger it.