diff --git a/doc/Architecture.md b/doc/Architecture.md index 0a16f9a..6b351a7 100644 --- a/doc/Architecture.md +++ b/doc/Architecture.md @@ -126,8 +126,6 @@ This application uses resources from Material Design. ### Localization -This application uses -[flutter_localization](https://pub.dev/packages/flutter_localization) to deal -with the localization of strings into multiple languages. +This application uses [flutter_localization](https://pub.dev/packages/flutter_localization) to deal with the localization of strings into multiple languages. See [Localization.md](Localization.md) for more details. \ No newline at end of file diff --git a/doc/AzurePipelines.md b/doc/AzurePipelines.md index de3d537..119a975 100644 --- a/doc/AzurePipelines.md +++ b/doc/AzurePipelines.md @@ -22,16 +22,22 @@ At high level, the CI/CD pipelines do the following: It also runs automated tests during the build steps. ### Pull request runs -Due to the length of mobile builds, pipelines are configured to behave a little differently when building in a context of **pull request (PR) build validation**. To reduce the build time, some stages and steps are disabled for PR builds. This requires a specific variable called `IsLightBuild` to be set, hence why it is appearing in the pipeline. + +Due to the length of mobile builds, pipelines are configured to behave a little differently when building in a context of **pull request (PR) build validation**. +To reduce the build time, some stages and steps are disabled for PR builds. +This requires a specific variable called `IsLightBuild` to be set, hence why it is appearing in the pipeline. Also, all release stages are disabled in the context of PR build validation because, with the optimizations differences, the resulting application would not represent the real thing. ### Release runs + Pipeline runs **triggered on the main branch** don't qualify for `IsLightBuild` and build the application with the goal of releasing it. All stages are therefore enabled. ## Stages and Steps + ### Build Stage ([stage-build.yml](../build/stage-build.yml)) + This file represents the stage that builds the applications on all platforms for any specified environment. It has many parameters, **the most important being the following**: - Application environment @@ -40,7 +46,8 @@ It has many parameters, **the most important being the following**: Note that variable groups and secured files are described in details in [`variables.yml`](../build/variables.yml). -This stage captures all the parameters required to build the application for all platforms and dispatches to work on parallel jobs. Each job is responsible for building the app on **one** platform. +This stage captures all the parameters required to build the application for all platforms and dispatches to work on parallel jobs. +Each job is responsible for building the app on **one** platform. - The iOS job runs on a **Mac** agent (because iOS apps can only be built on a Mac). - All other jobs run on a **Windows** agent. @@ -54,6 +61,7 @@ The steps for each job are encapsulated in **steps files**. `steps-build-release-notes.yml`| Generates release notes. ### Build Steps (steps-build.{...}.yml) + This is where the exact build steps are defined. These vary depending on the platform, but can be summarized as follows: 1. Install Flutter. 1. Install and run [GitVersion](https://gitversion.net/) to calculate the semantic version based on the Git history. @@ -67,12 +75,19 @@ This is where the exact build steps are defined. These vary depending on the pla The release stages are even more straigtforward than the build ones. One thing to note is that, for the same reason as it is done at the end of the build steps, a clean-up step is included in every stage. ### AppCenter Release Stage ([stage-release-appcenter.yml](../build/stage-release-appcenter.yml)) + This stage is in charge of pushing the Android application to AppCenter. ### Apple AppStore Release Stage ([stage-release-appstore.yml](../build/stage-release-appstore.yml)) -This stage is in charge of pushing the iOS version to the Apple AppStore. Given that the build stage signs the application, this is as simple as using the proper task and pushing the **IPA** file. This should only be run for configurations that properly sign the application. + +This stage is in charge of pushing the iOS version to the Apple AppStore. +Given that the build stage signs the application, this is as simple as using the proper task and pushing the **IPA** file. +This should only be run for configurations that properly sign the application. ### GooglePlay Console Release Stage ([stage-release-googleplay.yml](../build/stage-release-googleplay.yml)) -Similar to the App Store stage, this stage pushes the **AAB** produced by the build to the Google Play Store. This is also meant for a properly signed AAB. -This pipeline should be setup as a **scheduled pipeline** that runs every night and **should NOT be part of build validation**. PRs should not be blocked when APIs are down. +Similar to the App Store stage, this stage pushes the **AAB** produced by the build to the Google Play Store. +This is also meant for a properly signed AAB. + +This pipeline should be setup as a **scheduled pipeline** that runs every night and **should NOT be part of build validation**. +PRs should not be blocked when APIs are down. diff --git a/doc/DependencyInjection.md b/doc/DependencyInjection.md index 85e0050..49ed26b 100644 --- a/doc/DependencyInjection.md +++ b/doc/DependencyInjection.md @@ -4,7 +4,8 @@ We use [GetIt](https://pub.dev/packages/get_it) for any IoC related work. ## Registering -- You can register a singleton service using `GetIt.I.registerSingleton(ServiceImplementation())`. This service will be accessible from anywhere. +- You can register a singleton service using `GetIt.I.registerSingleton(ServiceImplementation())`. +This service will be accessible from anywhere. - You can register a service that will be created everytime you request it by using `GetIt.I.registerFactory(() => ServiceImplementation())`. @@ -27,6 +28,7 @@ We use [GetIt](https://pub.dev/packages/get_it) for any IoC related work. - If you can't use manual constructor injection, you can use `GetIt.I()` to resolve a service. This will throw an exception if the type `IService` is not registered. -- Circular dependencies will not work with this container. If you do have them, you might get an exception or an infinite loop. +- Circular dependencies will not work with this container. +If you do have them, you might get an exception or an infinite loop. - You can access the service provider **statically** using `GetIt.I`. diff --git a/doc/Diagnostics.md b/doc/Diagnostics.md index 285952d..8b840f7 100644 --- a/doc/Diagnostics.md +++ b/doc/Diagnostics.md @@ -4,6 +4,7 @@ This template comes with multiple built-in diagnostic tools. This is not available in the prod environment. ## Diagnostics Overlay + When you start the application, you'll notice a box on the side of the screen. This overlay shows a few buttons. The overlay is accessible from anywhere in your app. diff --git a/doc/Environment.md b/doc/Environment.md index c50dfc6..2257a68 100644 --- a/doc/Environment.md +++ b/doc/Environment.md @@ -38,7 +38,8 @@ ForcedUpdatePage({super.key}) { ## Diagnostics -Multiple environment features can be tested from the diagnostics overlay. This is configured in [EnvironmentPickerWidget](../src/app/lib/presentation/diagnostic/environment_picker_widget.dart). +Multiple environment features can be tested from the diagnostics overlay. +This is configured in [EnvironmentPickerWidget](../src/app/lib/presentation/diagnostic/environment_picker_widget.dart). - You can see the current runtime environment. - You can see what the environment will be overriden to. diff --git a/doc/KillSwitch.md b/doc/KillSwitch.md index 0795d06..b4844e5 100644 --- a/doc/KillSwitch.md +++ b/doc/KillSwitch.md @@ -5,6 +5,7 @@ This could be used for example when the server is down for some time, to avoid t To trigger the kill switch, we subscribe to the `isKillSwitchActivatedStream` `stream` from the `KillSwitchService` in the [Main](../src/app/lib/main.dart). -If the kill switch is activated, the user is brought to the `KillSwitchPage` where he can see a message that tells him the app is currently unavailable. If the kill switch is deactivated afterwards, the user is brought back to the initial navigation flow, which means he will be in the login page if he is not connected and to the home page if he is connected. +If the kill switch is activated, the user is brought to the `KillSwitchPage` where he can see a message that tells him the app is currently unavailable. +If the kill switch is deactivated afterwards, the user is brought back to the initial navigation flow, which means he will be in the login page if he is not connected and to the home page if he is connected. Whether the kill switch is activated or not on mobile and web platforms is defined in a [remote config](FirebaseRemoteConfig.md). diff --git a/doc/Navigation.md b/doc/Navigation.md index d2a74ce..6f5546f 100644 --- a/doc/Navigation.md +++ b/doc/Navigation.md @@ -11,8 +11,7 @@ To handle pages that share a menu, we use a [StatefulShellRoute](https://pub.dev To register a new section, you must add a stateful branch. Each branch represents a section. Each page you add below the primary route will have the shell and anything that comes with it (like the bottom navigation bar). -When you add a route nested in another route, if you navigate to that page and then navigate back, -it will navigate back to the parent page. +When you add a route nested in another route, if you navigate to that page and then navigate back, it will navigate back to the parent page. ```dart StatefulShellBranch( diff --git a/doc/Testing.md b/doc/Testing.md index f47fe18..4414b87 100644 --- a/doc/Testing.md +++ b/doc/Testing.md @@ -1,4 +1,5 @@ # Testing + For more documentation on testing, read the references listed at the bottom. ## Unit Testing @@ -189,21 +190,23 @@ flutter test integration_test --dart-define ENV=Development Otherwise it will throw unclear exceptions that don't point you at this issue. ## Code coverage + You can collect the code coverage locally using the following command lines. ### Installing lcov/genhtml In order to visualize the test coverage you need to install lcov and by extension genhtml. -On windows you need chocolatey and run this command +On windows you need chocolatey and run this command. ```bash chocolatey install lcov ``` -on macOS you need to have lcov installed on your system (`brew install lcov`) to use the `genhtml` command. +On macOS you need to have lcov installed on your system (`brew install lcov`) to use the `genhtml` command. -Then you need to add the genhtml path to your environment variables. Go to the properties of your pc then go to advanced system settings -> Environment variables, then in system variables find the -path variable and edit it. Add this path C:\ProgramData\chocolatey\lib\lcov\tools\bin and now open a git bash terminal against your src/app folder and enter these commands +Then you need to add the genhtml path to your environment variables. +Go to the properties of your PC then go to advanced system settings -> `Environment variables`, then in system variables find the path variable and edit it. +Add this path `C:\ProgramData\chocolatey\lib\lcov\tools\bin` and now open a git bash terminal against your `src/app` folder and enter these commands. ```bash # Generate `coverage/lcov.info` file @@ -231,7 +234,9 @@ There’s also a couple of VSCode extensions you can use to visualize your cover For both of these extensions to work, you must generate a `lcov.info` file before hand, or whenever you make a change and want to see your coverage. ## Naming -In general, test files should reside inside a `test` folder located at the root of your Flutter application or package. Test files should always end with `_test.dart`, this is the convention used by the test runner when searching for tests. + +In general, test files should reside inside a `test` folder located at the root of your Flutter application or package. +Test files should always end with `_test.dart`, this is the convention used by the test runner when searching for tests. Your file structure should look like this: ``` diff --git a/src/cli/CHANGELOG.md b/src/cli/CHANGELOG.md index a3436dd..892c341 100644 --- a/src/cli/CHANGELOG.md +++ b/src/cli/CHANGELOG.md @@ -5,6 +5,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) Prefix your items with `(Template)` if the change is about the template and not the resulting application. +## 0.19.2 +- Cleanup documentation. + ## 0.19.1 - Target specific Dart (>=3.4.0 <4.0.0) / Flutter (3.22.1) SDK.