Merge branch 'master' into refactor/answer-list-parser

cspell.config.yml

@@ -8,6 +8,7 @@
 # words - list of words to be always considered correct
 "words":
   [
+    "cocoapods",
     "danfojs",
     "dexie",
     "firebaserc",

documentation/docs/developers/building-and-deploying-to-ios.md

@@ -0,0 +1,59 @@
+# Building and deploying to iOS
+
+Building and deploying an app to iOS must be performed by a developer on a Mac computer. This guide does not include the process for managing the app within Apple's App Store Connect console, which is documented elsewhere (see [Apple's official documentation](https://developer.apple.com/help/app-store-connect/), or organisation-specific documentation is available from IDEMS devs on request).
+
+## Prerequisites
+
+### Apple Developer Account
+
+In order to create iOS applications, you will need to enrol in the [Apple Developer Program](https://developer.apple.com/programs/), which can be done as an individual or organisation.
+
+### XCode
+
+In order to run applications locally on an iOS device or simulator (Apple's term for an iOS device emulator), and submit them to the App Store, you will need XCode. [XCode](https://developer.apple.com/xcode/) is available from the Mac App Store.
+
+You will also need XCode CLI tools. These may have been installed with XCode, run `xcode-select -v` to check. If not already installed, run `xcode-select --install`. The CLI tools may need to be configured using the command `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`.
+
+### CocoaPods
+
+[CocoaPods](https://cocoapods.org/) is a dependency manager for iOS projects, and is required to build iOS apps via Capacitor. Installing via [Homebrew](https://brew.sh/) seems to be the best method, via the command `brew install cocoapods`.
+
+### Capacitor iOS setup
+
+The project is already configured to build to iOS using Capacitor. See the [Capacitor iOS Documentation](https://capacitorjs.com/docs/ios) for full details, or follow the steps below.
+
+## Build, sign and upload the iOS app
+
+### Building for the first time
+
+If the deployment has not previously been built for iOS, follow these steps
+
+1. Ensure that the deployment is fully configured to be built to iOS, in accordance with the instructions in the [deployments](./deployments.md#android-and-ios-management) section. In particular, ensure the deployment config has values set for 
+```ts
+config.ios.app_id = "international.idems.my-example-app"
+config.ios.app_name = "My Example App"
+```
+2. Run `yarn workflow ios configure` to generate the relevant iOS build files from the templated files using the values specified in the deployment config.
+3. Generate iOS assets (app icon and splash screen), using the [capacitor-assets](https://github.com/ionic-team/capacitor-assets) package. Alternatively, the assets can be generated in [XCode directly](https://developer.apple.com/documentation/xcode/configuring-your-app-icon) after step 6.
+4. Run `yarn build`
+5. Run `npx cap sync ios`
+6. Run `npx cap open ios` to open the project in XCode.
+7. Open the Firebase console and fetch the relevant `GoogleService-Info.plist` file for the deployment's registered app. Copy the file to `ios/App/App/GoogleService-Info.plist`.
+8. In order to sign the app, in XCode navigate to `App > Targets > App Signing & capabilities`. Set the value for the development team, using "Add account" if you have not previously configured XCode with a development team. Ensure that the option "Automatically manage signing" is checked.
+9. Now build the app to a target simulator to test functionality.
+10. When ready to upload the app to App Store Connect, set the target as "Any iOS device (arm64)", and go to `Product > Archive`.
+    ![](./images/xcode-target.png)
+11. The process of "archiving" converts your application into the format required to upload it to the App Store. Select "Distribute App" to publish the app to App Store Connect. You will still be able to test the app through TestFlight once it is uploaded before submitting to Apple for review. Choose the options to automatically manage signing and generate a certificate. Click "Upload", and once the process is complete, the app will be available for management through [App Store Connect](https://appstoreconnect.apple.com/apps). 
+
+### Subsequent builds
+
+If the deployment has previously been built for iOS, follow these simplified steps to build, test and deploy.
+
+1. Run `yarn workflow ios configure` to update the relevant iOS build files from the templated files using the values specified in the deployment config.
+2. Run `yarn build`
+3. Run `npx cap sync ios`
+4. Run `npx cap open ios` to open the project in XCode.
+5. Now build the app to a target simulator to test functionality.
+6. When ready to upload the app to App Store Connect, set the target as "Any iOS device (arm64)", and go to `Product > Archive`.
+    ![](./images/xcode-target.png)
+7. The process of "archiving" converts your application into the format required to upload it to the App Store. Select "Distribute App" to publish the app to App Store Connect. You will still be able to test the app through TestFlight once it is uploaded before submitting to Apple for review. Choose the options to automatically manage signing and generate a certificate. Click "Upload", and once the process is complete, the app will be available for management through [App Store Connect](https://appstoreconnect.apple.com/apps). 

documentation/docs/developers/code-releases.md

@@ -0,0 +1,9 @@
+# Code Releases
+
+Code releases should be made periodically, although there is no set schedule. The default code version that is targeted by deployments when building through GitHub actions is determined by the organisation variable, `APP_CODE_BRANCH`. Deployment repos can optionally set a repo-level variable with the same name to override this value and target a different code version.
+
+## Making a new code release
+1. Run `yarn run version --package` to bump the version number as specified in package.json.
+2. Commit these changes and merge a PR to master. This will update the version number of the latest draft release.
+3. Check the release notes of the draft release and publish it (edit the release and then select "Publish release").
+4. In order to update the default code version targeted by repos, update the organisation variable `APP_CODE_BRANCH` to point to the latest variable tag. To update a particular deployment's target code version, update or add the `APP_CODE_BRANCH` variable to that deployment's content repo. This will override the default value set by the organisation variable.

documentation/docs/developers/deployments.md

@@ -143,43 +143,48 @@ If for any reason the local content repo gets into a bad/conflicted state, it ca
 The content repo can be opened via shortcut `yarn workflow repo open`
 
 
-## Android Management
-For deployments that are intended to be published to the Google Play Store, some additional configuration is required.
+## Android and iOS Management
+For deployments that are intended to be published to the Google Play Store or the iOS App Store, some additional configuration is required.
 
 ### App ID and App Name
-The App ID uniquely identifies an Android app on devices and in the Google Play Store (see the official [Android developer docs](https://developer.android.com/build/configure-app-module#set-application-id) for more details). It is common to use the segments to identify your organisation and app in a reverse-dns format, e.g. `international.idems.my_example_app`, or `com.mycompany.example_app`.
+The App ID uniquely identifies an Android or iOS app on devices and in the Google Play Store (see the official [Android](https://developer.android.com/build/configure-app-module#set-application-id) and [Apple](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/) documentation for more details). It is common to use the segments to identify your organisation and app in a reverse-dns format, e.g. `international.idems.app`, or `com.mycompany.app`. The specifications for Android and iOS platforms are slightly different: for the Android app ID, all characters in each section must be alphanumeric or an underscore, e.g. `international.idems.my_example_app`, whereas for the Apple app ID, all characters must be alphanumeric or a hyphen, e.g. `international.idems.my-example-app`.
 
 !!! warning
-    Android app IDs must contain at least 2 segments (one or more dots) and once set cannot be changed. So consider carefully how the id may be used in the future to represent your app. 
+    App IDs must contain at least 2 segments (one or more dots) and once set cannot be changed. So consider carefully how the id may be used in the future to represent your app. 
 
 
-The App Name is the name that will be displayed to users on devices and in the Google Play Store.
+The App Name is the name that will be displayed to users on devices and in the Google Play Store or App Store.
 
-These values must be set in the deployment config before the app can be built as an Android bundle.
+These values must be set in the deployment config before the app can be built as an app bundle.
 
 For example:
 ```ts
 config.android.app_id = "international.idems.my_example_app";
 config.android.app_name = "My Example App";
+
+config.ios.app_id = "international.idems.my-example-app";
+config.ios.app_name = "My Example App";
 ```
 
 ### Versioning
-In order to build for Android, the deployment config must contain a valid value for the property `config.git.content_tag_latest` (see [Github management](#github-management)). This value can be changed manually, or via the command:
+In order to build for Android or iOS, the deployment config must contain a valid value for the property `config.git.content_tag_latest` (see [Github management](#github-management)). This value can be changed manually, or via the command:
 ```sh
 yarn scripts version --content (--auto-patch)
 ```
 
 ### Google Services
-Connecting to Firebase is currently required by all Android apps. Follow the instructions for [Firebase management](#firebase-management) for native platforms in order to set this up for a new deployment.
+Connecting to Firebase is currently required by all native apps. Follow the instructions for [Firebase management](#firebase-management) for native platforms in order to set this up for a new deployment.
 
 ### Generating an app icon and splash screen
-See [Android Assets](./android-assets.md).
+For generating Android assets, see [Android Assets](./android-assets.md).
+
+For generating iOS assets, it is recommended to use [xcode directly](https://developer.apple.com/documentation/xcode/configuring-your-app-icon), or the [capacitor-assets](https://github.com/ionic-team/capacitor-assets) package. This process should be streamlined in the future.
 
 ## Firebase management
 Firebase is used to provide some services such as authentication and crashlytics. Currently, even apps that do not use these services explicitly must be linked to a corresponding Firebase project in order to be built for native devices. Exclusively local and web deployments do not require Firebase to be configured, unless they make use of these features.
 
 ### Native platforms
-For apps that target Android, a corresponding "Android app" should be added to a linked Firebase project, with an `Android package name` matching the `app_id` for the deployment (see [Android Management](#android-management)). The relevant `google-services.json` file should be downloaded, and copied to `android/app/google-services.json` for building the Android app locally, or its contents copied into a `GOOGLE_SERVICES_JSON` secret in the deployment's Github repo, for building the Android app via github action.
+For apps that target native platforms (Android or iOS), a corresponding "Android app" or "Apple app" should be added to a linked Firebase project, with an `Android package name` or `Apple bundle ID` matching the `app_id` for the respective platform specified in the deployment config (see [Android and iOS Management](#android-and-ios-management)). The relevant `google-services.json` or `GoogleService-Info.plist` file should be downloaded, and copied to `android/app/google-services.json` or `ios/App/App/GoogleService-Info.plist` for building the native app locally, or its contents copied into a `GOOGLE_SERVICES_JSON` secret in the deployment's Github repo, for building the Android app via github action.
 
 ### Enabling Firebase features
 To enable Firebase features, a Firebase config must be included in the deployment config. 

documentation/mkdocs.yml

@@ -32,6 +32,8 @@ nav:
       - developers/in-app-updates.md
       - developers/error-logs.md
       - developers/web-previews.md
+      - developers/code-releases.md
+      - developers/building-and-deploying-to-ios.md
   - Display Components:
       - components/audio.md
       - components/button.md