Update documentation

- rework "automation.md" and update to recent changes
- add "release_management.md"
- add "development.md"
- minor cleanup

docs/architecture_agent.md

@@ -1,4 +1,4 @@
-# Agent architecture description
+# Agent architecture
 
 **Table of contents:**
 

docs/architecture_model.md

@@ -1,4 +1,4 @@
-# Model architecture description
+# Model architecture
 
 **Table of contents:**
 

docs/architecture_overview.md

@@ -1,4 +1,4 @@
-# Application architecture description
+# Application architecture
 
 **Table of contents:**
 
@@ -28,4 +28,4 @@ The roc-droid modules are described in the following documents:
 
 * **Model** – [Model architecture description](/docs/architecture_model.md)
 
-* **Agent** – [Agent architecture description](/docs/architecture_agent.md)
+* **Agent** – [Agent architecture description](/docs/architecture_agent.md)

docs/architecture_ui.md

@@ -1,4 +1,4 @@
-# User interface architecture description
+# User interface architecture
 
 **Table of contents:**
 

docs/automation.md

@@ -1,60 +1,112 @@
-# Description of application automation (doit)
+# Automation
 
-> **Note:** All commands are called from the root directory (using terminal).
+## Prerequisites
 
-**Table of contents:**
+Commands below need Python3 and [doit](https://pydoit.org/) automation tool.
 
-- [Description of application automation (doit)](#description-of-application-automation-doit)
-  - [Starting dart models code generation](#starting-dart-models-code-generation)
-  - [Starting application icons generation](#starting-application-icons-generation)
-  - [Starting application splash screen generation](#starting-application-splash-screen-generation)
+All commands are called from the root directory (using terminal).
 
-## Starting dart models code generation
+## Run linters
 
-Code generation is based on the Flutter `build_runner` package.
+Run all code checks (dart analyzer, kotlin linter, etc):
 
-Code generation is initiated by the following command:
+```
+doit lint
+```
+
+Run individual checks:
 
 ```
-doit gen
+doit lint:dart
+doit lint:kotlin
+```
+
+## Run tests
+
+Run tests on desktop:
+
+```
+doit test
+```
+
+## Build and clean
+
+Build for all platforms:
+
+```
+doit build [variant=debug|release]
+```
+
+Build Android APK:
+
+```
+doit build:apk [variant=debug|release]
+```
+
+Clean build artifacts:
+
+```
+doit wipe
 ```
 
-The code is generated into special `Store` files with the extension `.g.dart` and is used by the `Mobx` package.
+## Launch app
 
-Code generated files (avoid any manual manipulation!):
+Build and launch application:
+
+```
+doit launch [variant=debug|release]
+```
 
-* Receiver generated code: [receiver.g.dart](/lib/src/model/receiver.g.dart)
+## Generate code
 
-* Sender generated code: [sender.g.dart](/lib/src/model/sender.g.dart)
+Code generation is based on `build_runner` package.
 
-## Starting application icons generation
+Run all code generators:
 
-Icons generation is based on the Flutter `flutter_launcher_icons` package.
+```
+doit gen
+```
 
-Icons generation is initiated by the following command:
+Run individual steps:
 
 ```
-doit icons
+doit gen:model [watch=true|false]
+doit gen:agent
 ```
 
-Icon generation settings are configured in the `pubspec.yaml` file in the `flutter_launcher_icons` section.
+`watch` parameter runs code generator in watch mode, when it monitors source files updates and automatically regenerates code when needed.
 
-The assets for generating icons are defined in the `pubspec.yaml` file in the `assets` section.
+Generated files have `*.g.dart` or `.g.kt` extension and must no be modified by hand.
 
-All assets are located in the corresponding `assets` folder in the root directory.
+`model` package uses `mobx_codegen` to generate reactive model classes. `agent` package uses `pigeon` to generate android platform channels bridge.
 
-## Starting application splash screen generation
+## Generate assets
 
-Splash screen generation is based on the Flutter `flutter_native_splash` package.
+Icons and splash screen are generated using `flutter_launcher_icons` and `flutter_native_splash` packages. You can find configuration in `pubspec.yaml` and source assets in `assets` directory.
 
-Splash screen generation is initiated by the following command:
+Regenerate icons:
 
 ```
-doit splash
+doit gen:icons
 ```
 
-Splash screen generation settings are configured in the `pubspec.yaml` file in the `flutter_native_splash` section.
+Regenerate splash screen:
 
-The assets for generating splash screen are defined in the `pubspec.yaml` file in the `assets` section.
+```
+doit gen:splash
+```
+
+## Format code
+
+Run all code formatters:
 
-All assets are located in the corresponding `assets` folder in the root directory.
+```
+doit fmt
+```
+
+Run individual steps:
+
+```
+doit fmt:dart
+doit fmt:kotlin
+```

docs/development.md

@@ -0,0 +1,13 @@
+# Development
+
+## Capture android logs
+
+This script is a wrapper for `adb logcat`:
+
+```
+python3 ./script/android_logcat.py
+```
+
+It filters out irrelevant logs and adds nice formatting and colorization (each log tag is assigned its own color).
+
+Unlike `flutter run`, you can launch it before the app when you need logs from the very early stages of initialization.

docs/install_win.md

@@ -1,8 +1,8 @@
-# Windows Flutter setup:
+# Flutter setup on Windows
 
 **Table of contents:**
 
-- [Windows Flutter setup:](#windows-flutter-setup)
+- [Flutter setup on Windows:](#flutter-setup-on-windows)
   - [Choco installation (optional, but recommended)](#choco-installation-optional-but-recommended)
   - [Flutter installation](#flutter-installation)
   - [Android Studio installation](#android-studio-installation)

docs/release_management.md

@@ -0,0 +1,67 @@
+# Release management
+
+## Publishing release
+
+To release a new version of the app, use `version_ctl.py` script.
+
+1. Update manifests, create git tag, and push it to GitHub:
+
+   ```
+   python3 ./script/version_ctl.py make_release --push origin 1.2.3
+   ```
+
+   (You also can omit `--push` to limit script to local changes only, and then push manually).
+
+2. Wait until "release" job on GitHub CI completes and creates GitHub release draft.
+
+    The draft will have release binaries attached, including a signed APK for Android.
+
+3. Go to release draft, edit description, and publish it.
+
+## About project version
+
+Project version is defined by a git tag and two files:
+
+* `pubspec.yaml` - flutter configuration
+* `AndroidManifest.xml` - android-specific configuration
+
+When publishing release, all three versions (git, flutter, android) must be set to the same value.
+
+When CI build a release, it runs `version_ctl.py check_release` to verify that the versions are consistent. When you run `version_ctl.py make_release` command as described above, it automatically applies all needed changes before making a tag.
+
+You can also update pubspec and manifest without making a release using this command:
+
+```
+python3 ./script/version_ctl.py update_version 1.2.3
+```
+
+## About APK signing
+
+Keystore with certificates was generated using this command:
+
+```
+keytool -genkey -v -keystore roc-droid.jks -alias apk -keyalg RSA -keysize 2048 -validity 10000
+```
+
+Then it was encoded to base64:
+
+```
+base64 roc-droid.jks
+```
+
+Then the following secrets were added to the repo:
+
+* `SIGNING_STORE_BASE64` - base64-encoded keystore (`roc-droid.jks`)
+* `SIGNING_STORE_PASSWORD` - keystore password
+* `SIGNING_KEY_ALIAS` - key alias (`apk`)
+* `SIGNING_KEY_PASSWORD` - key password (same as keystore password)
+
+GitHub actions decode `SIGNING_STORE_BASE64` into a temporary `.jks` file and set `SIGNING_*` environment variables with the name of the file and credentials.
+
+Then the following command is run:
+
+```
+doit build:apk variant=release
+```
+
+It reads credentials from the environment variables and signs release APK using them.