Update docs

davecraig · davecraig · commit f63dae9beb19 · 2025-07-11T09:31:49.000+01:00
diff --git a/app/src/main/res/drawable/soundscape_alpha_512.png b/app/src/main/res/drawable/soundscape_alpha_512.png
diff --git a/docs/README.md b/docs/README.md
@@ -1,11 +1,11 @@
 ## Project aim
-The project is creating an Android version of the original [iOS Soundscape app](https://www.scottishtecharmy.org/soundscape). The app aims to help people with visual impairment explore and navigate the world. 
+The project is creating an Android version of the original [iOS Soundscape app](https://www.scottishtecharmy.org/soundscape). The app aims to help people with visual impairment explore and navigate the world.
 
 ## For users
-We now have an app which has many of the features available which are available in the iOS app. It is still relatively early days in the project, but we have started initial user testing taking place via the Google Play Store. Currently this is 'internal' testing which means that to access the app you're name needs to be on a list of approved testers. If you're interested in helping us with testing please use this [contact form](https://www.scottishtecharmy.org/contact-us) and we'll add you to the list.
+We now have a fairly complete app which has the majority of the features available that are in the iOS app. It's been in internal testing and we hope to soon have the app available for Beta testing which means that it will be openly available on the Google Play Store.
 
 ## For developers
 Documentation for developers is available [here](developers.md).
 
 ## Localization
-We have started using the fantastic [Weblate](https://hosted.weblate.org/projects/soundscape-android/) to help with the localization of the app.
+We have started using the fantastic [Weblate](https://hosted.weblate.org/projects/soundscape-android/) to help with the localization of the app. We started off supporting the same languages as supported in iOS, but we have some new strings in the Android app and so there are some missing translations in most languages. All help in adding these, or indeed adding new languages will be gratefully received. A description of how this works can be found [here](https://docs.weblate.org/en/latest/user/translating.html). When you set up a Weblate account, you choose which languages you can translate to and if the Soundscape app doesn't currently support that language, you will have the option of adding that language on the main app [page](https://hosted.weblate.org/projects/soundscape-android/android-app/).
diff --git a/docs/actions.md b/docs/actions.md
@@ -1,8 +1,15 @@
 # Continuous integration actions
 
-This document describes the initial GitHGub actions in the repo. They're written by someone new to GitHub, so improvements are always welcome. 
+This document describes the GitHGub actions in the repo. They're written by someone new to GitHub, so improvements are always welcome. 
 
 ## GitHub secrets
+
+We have a number of GitHub secrets which are used to protect the following data:
+* Keys used for creating release packages and accessing Google service. These prevent someone else from publishing a build that claimed to be our app.
+* The URL and key required to get map tiles from our protomaps server. The aim here is to prevent use of our map tile server by other apps. Our server costs are covered by charities and we simply aim to minimize their costs.
+
+More details follow on each secret here which is useful during setup.
+
 ### Release build signing
 The approach to signing in `build-app.yaml` is based on [this description](https://www.droidcon.com/2023/04/04/securely-create-android-release-using-github-actions/).
 
@@ -33,21 +40,30 @@ The `run-test.yaml` action bumps the version number, committing the change back
 * PAT_TOKEN - token generated on an admin account which allows write access to public repos.
 
 ## Actions
-`run-tests.yaml` is the action which is run on each Pull Request. It runs several layers of tests:    
+### Run tests `run-tests.yaml`
+This is the action which is run on each Pull Request. It runs several layers of tests:    
 * Lint of the repo
 * Runs unit tests
 * Builds a debug release
 * Runs instrumentation tests locally on an emulator
 
-`build-app.yaml` is the action used to build a release and is manually triggered. It's steps are: 
+Note that because of the way GitHub triggers `run-tests.yaml` it cannot use secrets. This affects tests which use the tile provider which have to be skipped when run in this way. This is straightforward to do - see callers of `tileProviderAvailable()` in the test code.
+
+### Tag and build release `build-app.yaml`
+This is the action used to build a release and is manually triggered from the GitHub GUI. It's steps are: 
 * Bump the version code and name in `app/build.gradle.kts` and commit it back to the repo with a tag containing the version number
 * Obtains the `google-service.json` and `keystore.jks` from the secrets.
 * Lints the repo
 * Runs unit tests
 * Builds a debug build APK
 * Builds a release build and signs it as an APK and AAB
 * Builds the instrumentation tests into an APK
-* Uploads the artefacts
-* Triggers a run of Firebase instrumentation tests  
+* Uploads the artifacts
+* Triggers a run of Firebase instrumentation tests
+* Triggers a run of Firebase robo tests
+
+### Deploy docs `jekyll-gh-pages.yml`
+This is the action to build the GitHub Pages documentation site (including this page!). It's triggered whenever there is a changes submitted within the `/docs` directory. To work it needs GitHub Pages to be enabled on the repository and for them to be configured with the Source being GitHub Actions.
 
-`jekyll-gh-pages.yml` is the action to build the GitHub Pages documentation site (including this page!). It's triggered whenever there is a changes submitted within the `/docs` directory. To work it needs GitHub Pages to be enabled on the repository and for them to be configured with the Source being GitHub Actions. 
+### Nightly build and test `nightly.yaml`
+This is similar to the code that tags and builds a release, the main difference being is that it doesn't bump the version number and it only builds a debug version of the app. It does run the instrumentation tests locally followed by the Firebase tests on the release.
diff --git a/docs/developers.md b/docs/developers.md
@@ -1,8 +1,5 @@
 # Developer information
-The app is developed using [Android Studio](https://developer.android.com/studio) with the majority of the app code written in Kotlin. 
-
-## Progress
-We now have an app which has many of the features available which are available in the iOS app, though it is still relatively early days in the project. 
+The app is developed using [Android Studio](https://developer.android.com/studio) with the majority of the app code written in Kotlin.
 
 ## Get started
 The quickest way to get started building the app is to run Android Studio and select `File/New/Project from version control` from the menu. Select `Git` as the version control and paste in the HTTPS code link for this project from above. Click on Clone and the project will download, open and initialize ready to build.
