Merge pull request #129 from AlexPerathoner/repo/docs

Add repo docs

.github/workflows/swift-lint.yml

@@ -2,6 +2,8 @@ name: Style fix and check
 on:
   pull_request:
     branches: ["master", "develop"]
+    paths:
+      - '**.swift'
 
 jobs:
   swift-lint:

.github/workflows/xcode-build.yml

@@ -1,7 +1,15 @@
 name: Build and Analyze
 on:
   pull_request:
+    paths:
+      - 'SlimHUD/**'
+      - 'SlimHUDTests/**'
+      - 'SlimHUDUITests/**'
   push:
+    paths:
+      - 'SlimHUD/**'
+      - 'SlimHUDTests/**'
+      - 'SlimHUDUITests/**'
     branches:
       - develop
   workflow_dispatch:
@@ -11,7 +19,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  test-results-check-name: Unit Test results
+  test-results-check-name: Test results
 
 jobs:
   unit-tests-run:

dev-docs/README.md

@@ -1,8 +1,74 @@
-# Developer documentation
+
+# Developer documentation
+
 
 This directory contains developer documentation for SlimHUD.
 
 ## How to build
 
 1. Clone the repository
-2. Open the project in Xcode (open `SlimHUD.xcodeproj`, )
+2. Open the project in Xcode (open `SlimHUD.xcodeproj`)
+3. Wait for Swift Package Manager to download the dependencies. See [Dependencies](#dependencies) for more info.
+3. Build the project (⌘B)
+4. Run the project (⌘R)
+
+## Dependencies
+
+- MediaKeyTap: needed to listen for media key presses (volume, brightness, play/pause, etc.), which triggers the HUDs.
+- Sparkle: needed to support automatic updates. See [Detailed release process](dev-ops/README.md#detailed-release-process) for more info.
+- SwiftImage: needed to access pixel colors from the screen, used in UI tests. See [Testing](#testing) for more info.
+
+## Basic concepts
+
+### HUDs
+
+HUDs are the different elements that are displayed on the screen. They are windows that are always on top of other windows, non clickable and transparent.
+There are 3 HUDs:
+- volume
+- brightness
+- keyboard brightness
+
+A HUD contains a BarView
+
+### BarView
+BarViews are the non-transparent parts of HUDs. Each contains an icon and a ProgressBar
+
+### ProgressBar
+Bars with a float value between 0 and 1. They are used to display the current value of the HUD.
+
+### Customization
+Each HUD and Bar has a set of customizable properties. Most can be changed for each HUD individually, but some are global (see configs in Design tab).
+
+## Architecture
+
+### Controllers
+> connect UI elements to SettingsManager
+- all ..Controller classes in SlimHUD/Controllers/SettingsViewController
+- MainMenuController: handles the menu bar icon and shortcuts for the settings window
+- SettingsWindowController: handles the displaying of the preview hud, when the settings window is open
+
+### Services
+> handle the logic of the HUDs
+
+![services](services.png)
+
+<details>
+  <summary>Description of summary</summary>
+
+- KeyPressObserver: main class, listens for media key presses and notifies the ChangesObserver
+- **SettingsManager**: stores all settings, reads them from the user defaults on launch and writes them to the user defaults when they change
+    - UserDefaultsManager: utility class to simplify the reading and writing of user defaults, used by the SettingsManager
+- **ChangesObserver**: stores the current values of the HUDs, check if they change and notifies the Displayer when they change
+    - KeyboardManager: used by the ChangesObserver to get the current keyboard brightness
+    - VolumeManager: used by the ChangesObserver to get the current volume info, calls AppleScriptRunner
+        - AppleScriptRunner: runs AppleScript code, allows to get output volume info
+- **Displayer**: shows the HUDs, when notified by the ChangesObserver
+    - **PositionManager**: used by the Displayer to calculate the position of the HUDs on the screen
+    - HudAnimator: used by the Displayer to animate the HUDs with the correct style
+    - IconManager: used by the Displayer to retrieve the icons for the HUDs
+- OSDUIManager: used by the AppDelegate to hide the default MacOS HUDs when SlimHUD is launched and to show them again when SlimHUD quits
+- UpdaterDelegate: used by Sparkle to get the channel to update from
+
+</details>
+
+Reality is more complex, but this gives a good overview of the main functioning. Classes that differ from the diagram could / should probably be refactored.

dev-docs/dev-ops/README.md

@@ -0,0 +1,72 @@
+
+## CI
+
+List of CI jobs:
+- release.yml: triggered by `/release` comment on a pull request. Can also be triggered by `/release beta` to create a beta release.
+- swift-lint.yml: triggered by pushes. Runs SwiftLint on the project using the `.swiftlint.yml` configuration file. Runs with `--fix` to automatically fix some issues.
+- xcode-build.yml: triggered by pushes to pull requests and to develop. Builds the project in Xcode and runs the tests. Takes long time to run due to UI tests.
+
+In addition to these jobs, [SonarCloud](https://sonarcloud.io/project/overview?id=alexpera_slimhud) is used to analyze the code quality. It is triggered inside the `xcode-build.yml` job.
+
+## Testing
+
+### UI Tests
+
+UI tests are
+- flaky
+- slow
+
+For these reasons the current configuration is as follow:
+- Pushes to `develop` and pull requests to `develop` run `xcode-build.yml` which runs the UI tests.
+    - Being flaky, failing UI tests are tried again up to 20 times. If they fail 20 times, they are marked as failed by the `xcodebuild` exit code.
+- Once the tests ran in `xcode-build.yml`, another check is created with the name "Test Results". This check:
+    - ..includes a report of all tests and the coverage. 
+    - ..will always succeed, independently of the result of any test. This is because tests which have failed multiple times, and then succeeded, are marked as failed (multiple times) in the report.
+- If tests do fail, the `xcode-build.yml` job will fail, and the "Test Results" check will be marked as successful. In `xcode-build.yml`'s logs, the failed tests will be listed. In the "Test Results" check, there will be additional information about the failed tests (including screenshots, for UI tests).
+
+## Releasing
+
+1. Make sure [Release notes](../ReleaseNotes.md) are up to date and formatted correctly:
+    ```markdown
+    # x.y.m - Title latest release
+    * Feature 1
+    * Feature 2
+
+    # x.y.n - Title of previous release
+    ...
+    ```
+2. Create a pull request `develop` -> `master`, wait for CI. See [CI](#ci) for more info.
+3. Comment `/release` on the pull request to trigger the release process. See [Detailed release process](#detailed-release-process) for more info.
+
+## Detailed release process
+
+![Release process](release-process.png)
+
+1. Preparation job
+    1. Triggered by `/release` comment on a pull request to `master`. Or by `/release beta` to create a beta release.
+    2. Retrieve signing certificates from GitHub secrets.
+    3. Build the project in Xcode.
+    4. Check if PR is ready to be merged (no conflicts, no pending reviews, etc.).
+    5. Extract latest changes from `ReleaseNotes.md`.
+    6. Generate html changelog from `ReleaseNotes.md` for Sparkle.
+    7. Check if version is valid (must be higher than previous version).
+    8. Check if there is at least one new feature.
+    9. Merge `master` into `develop` to keep them in sync. This is needed because a beta release is created directly on `master`.
+2. Build and export
+    1. Replace version in project with version in `ReleaseNotes.md`.
+    2. Install provisioning profiles and signing certificates. See [release.yml](/.github/workflows/release.yml) for more info.
+    3. Use latest Xcode version
+    4. Build and archive the project.
+    5. Export the archive as a `.zip` file.
+3. Release / Release beta
+    1. Update `appcast.xml` with the Sparkle tool. Publish to beta channel if beta release. Construct download URL from GitHub release.
+    2. Commit changes
+        - Beta: only appcast file, directly on `master`.
+        - Normal release: appcast file and project file (version update) on `develop`, then merge PR.
+    3. Create GH release with the `.zip` file and the changelog.
+4. Upgrade Homebrew
+    1. SlimHUD is available on Homebrew Cask. This job updates the cask formula. See [homebrew bump-cask-pr](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request) for more info.
+5. Finish up
+    1. Add reaction to the PR to indicate the release process is finished.k
+    2. Update deployment status in GH
+    3. Delete artifacts (used to share data between jobs)