From b68854be63ced496bfb155045b68ad815fc53da8 Mon Sep 17 00:00:00 2001 From: shaun0927 Date: Wed, 21 Oct 2026 13:49:18 +0900 Subject: [PATCH 1/2] docs: prevent incorrect assumptions about CI coverage Align contributor guidance and the job inventory with the current workflow while preserving the real-device smoke-test requirement. Tested: npm run docs:check; git diff --check; compared job inventory with ci.yml Confidence: high Scope-risk: narrow --- .harness/docs/git-workflow.md | 5 ++-- AGENTS.md | 4 ++-- .../engineering/ci-workflows.md | 24 ++++++++++++++----- .../testing/writing-tests.md | 2 +- 4 files changed, 24 insertions(+), 11 deletions(-) diff --git a/.harness/docs/git-workflow.md b/.harness/docs/git-workflow.md index 1e67d6428a..e522df3ca2 100644 --- a/.harness/docs/git-workflow.md +++ b/.harness/docs/git-workflow.md @@ -21,7 +21,7 @@ Conventions for the Mavis reins when working in this repo. ## CI (`.github/workflows/ci.yml`) -CI runs on every PR to `main`, `feat/ai-edition` and `release/**`, and on every push to those: +CI runs on every PR to `main`, `feat/ai-edition`, `release/**` and `integration/**`, and on every push to those: - `npm run lint` (Biome) - `npx tsc --noEmit` (TypeScript, app code) - `npx tsc -p tsconfig.test.json --noEmit` (TypeScript, test files — a separate gate at zero) @@ -29,8 +29,9 @@ CI runs on every PR to `main`, `feat/ai-edition` and `release/**`, and on every - `npm run docs:check` - `npx vite build` (renderer build smoke) - `cargo test` / `cargo check` for the compositor on macOS, Windows and Linux +- `swift test` and a release build of both macOS capture helpers -All must be green before merge. Native helper code is NOT covered by CI — manual smoke test is required for `electron/*-helper/` changes; note it in the PR description. +All must be green before merge. The macOS helpers have compile and unit-test coverage, but CI does not exercise real capture, permissions or devices. Manual smoke tests on the affected platforms are still required for native changes; note them in the PR description. See the [CI job inventory](../../technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci) for the exact checks and runners. ## Pull request flow diff --git a/AGENTS.md b/AGENTS.md index 268e565674..0f53b8cfc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,7 +70,7 @@ every edit is the main way an agent turns a 5-minute task into a 30-minute one, defined`. Don't add it to a test that doesn't need it: jsdom setup dominates this suite's runtime (see the comment in `vitest.config.ts`). - Anything platform-conditional (`process.platform`) must pin the platform in the test. - CI is Linux-only, so a Linux-only code path left unpinned is green in CI and red on + The Vitest CI job runs only on Linux, so a Linux-only code path left unpinned is green in CI and red on every Windows and macOS machine — `electron/recording/webm-seek-index.test.ts` is the worked example. - E2E tests are in `tests/e2e/` (Playwright). Some specs are platform-specific (e.g. `windows-native-checklist.spec.ts`). @@ -171,7 +171,7 @@ The one rule to know before you merge anything: **there is one release branch pe ## Specialized notes -- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI runs on Linux only — manual smoke test on real macOS/Windows is required for native changes. +- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI tests and builds the macOS Swift helpers and checks the compositor on macOS, Windows and Linux. These checks do not exercise real capture, permissions or devices; manual smoke tests on the affected platforms are still required for native changes. See [CI coverage](technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci). - **Rendering is native**: the Rust compositor in `crates/compositor/` renders the editor preview and every export, MP4 and GIF. It runs on Direct3D 11 on Windows, Metal on macOS and wgpu on Linux, with a CPU fallback on Windows and Linux. The renderer only paints the preview frames it pulls onto a ``. Details: `technical-documentation/README.md`, then `architecture/native-compositor.md`. - **i18n**: 15 locales in `src/i18n/locales//` (e.g. `src/i18n/locales/en/settings.json`). The `i18n:check` script validates them — run it after touching translation files. - **Website i18n** is separate: 8 locales under `website/i18n/`. After changing an English doc, page or `` string in `website/`, follow `website/i18n/TRANSLATING.md` ("Keeping translations up to date"); `npm run i18n:check` in `website/` lists what is behind. diff --git a/technical-documentation/engineering/ci-workflows.md b/technical-documentation/engineering/ci-workflows.md index cc3ecea656..a87ca6734d 100644 --- a/technical-documentation/engineering/ci-workflows.md +++ b/technical-documentation/engineering/ci-workflows.md @@ -7,9 +7,12 @@ The repository's 15 workflow files under `.github/workflows/` cover application ```mermaid flowchart TD subgraph T1["Tier 1 — application and docs CI"] - CI["ci.yml
push and PR to main"] --> Lint[lint] - CI --> Type[typecheck] - CI --> Test[unit and browser tests] + CI["ci.yml
push and PR to configured branches"] --> Lint[lint] + CI --> Type[app and test typechecks] + CI --> Test[Vitest unit tests] + CI --> TechnicalDocs[technical documentation check] + CI --> Native["Rust compositor checks
macOS, Windows, Linux"] + CI --> Swift[macOS Swift tests and release build] CI --> BuildSmoke[Vite build] CI --> Semantic[semantic PR title] Docs["docs.yml
website changes or dispatch"] --> DocsBuild[website build artifact] @@ -58,7 +61,7 @@ The STT workflow uploads standalone archives for binary refresh and does not cur | Tier | Workflow | Trigger | |---|---|---| -| 1 | `ci.yml` | Push to `main`; pull request to `main` | +| 1 | `ci.yml` | Push and pull request to `main`, `feat/ai-edition`, `release/**` or `integration/**` | | 1 | `docs.yml` | Website/workflow changes on `main` or a PR; manual dispatch | | 2 | `build.yml` | Any `v*` tag; manual dispatch | | 2 | `build-whisper-stt.yml` | Native STT/build-script changes; manual dispatch | @@ -75,17 +78,26 @@ The STT workflow uploads standalone archives for binary refresh and does not cur ## Tier 1: application and documentation CI -`ci.yml` runs independent `lint`, `typecheck`, `test`, and renderer-build jobs. Pull requests also run `semantic-pr`. +[`ci.yml`](../../.github/workflows/ci.yml) runs the following independent jobs on pushes and pull requests to `main`, `feat/ai-edition`, `release/**` and `integration/**`. Only `semantic-pr` is restricted to pull requests. | Job | Runner | Command or purpose | |---|---|---| | `lint` | Ubuntu | `npm run lint` | | `typecheck` | Ubuntu | `npx tsc --noEmit` | -| `test` | Ubuntu | Vitest unit tests, Chromium installation, then browser-mode Vitest | +| `typecheck-tests` | Ubuntu | `npx tsc -p tsconfig.test.json --noEmit` | +| `docs` | Ubuntu | `npm run docs:check` for `technical-documentation/` and `.harness/` | +| `test` | Ubuntu | `npm run test` (Vitest unit tests; no browser-mode step) | | `build` | Ubuntu | `npx vite build`; this is not electron-builder packaging | | `appstream` | Ubuntu | `appstreamcli validate` on `build/com.getopenscreen.OpenScreen.metainfo.xml` | +| `rust-macos-compositor-check` | `macos-latest` (arm64) | `cargo test -p openscreen-compositor --lib --tests`, then `cargo build -p compositor-view-napi --release` | +| `rust-macos-intel-compositor-check` | `macos-15-intel` | Metal-device probe, then `cargo test -p openscreen-compositor --lib --tests` | +| `rust-windows-compositor-check` | `windows-latest` | `cargo check -p openscreen-compositor -p compositor-view-napi --all-targets` | +| `rust-linux-compositor-check` | `ubuntu-latest` | `cargo test -p openscreen-compositor --lib --tests`, then `cargo build -p compositor-view-napi --release` | +| `swift-macos-helper` | `macos-latest` | `swift test` and `swift build -c release` for `electron/native/screencapturekit` | | `semantic-pr` | Ubuntu | Validates Conventional Commit-style PR titles | +The Vitest job is Linux-only; the native jobs do not change that, so platform-conditional TypeScript tests must still pin `process.platform`. The Windows compositor job checks compilation rather than running its tests. None of these jobs replaces the [manual desktop pass](../testing/manual-e2e-checklist.md) for real recording, OS permissions or physical devices. + `build/com.getopenscreen.OpenScreen.metainfo.xml` is upstream AppStream metadata: the name, summary, description, licence, screenshots and release history a software centre shows instead of a bare icon. Nothing in this repository consumes it yet — the shipped deb installs a `.desktop` file and nine icon sizes and no `/usr/share/metainfo/` at all — so the `appstream` job is the only thing that can catch a broken edit before a Flathub reviewer does. Its component ID is `com.getopenscreen.OpenScreen`, deliberately not the Electron `appId` `com.etiennelescot.openscreen`: Flathub requires the ID to map to a domain the project controls, and `getopenscreen.com` is that domain. Jobs that need the root dependencies use `.github/actions/setup`, which requests Node 22 and runs `npm ci`; callers perform checkout themselves. diff --git a/technical-documentation/testing/writing-tests.md b/technical-documentation/testing/writing-tests.md index 83ae0a98b7..a464690c48 100644 --- a/technical-documentation/testing/writing-tests.md +++ b/technical-documentation/testing/writing-tests.md @@ -43,7 +43,7 @@ it only if it renders a component, uses `renderHook`, or reaches for a browser g ### Platform-conditional code -CI runs on Linux only. A test covering a `process.platform`-gated path must pin the +The Vitest CI job runs only on Linux. A test covering a `process.platform`-gated path must pin the platform itself, or it passes vacuously in CI and fails on every Windows and macOS machine. `electron/recording/webm-seek-index.test.ts` sets `process.platform` in `beforeEach` and restores it in `afterEach` — copy that shape. From b08621ec77f4e1d5734912df808af6bb053b2764 Mon Sep 17 00:00:00 2001 From: shaun0927 Date: Wed, 21 Oct 2026 13:56:46 +0900 Subject: [PATCH 2/2] docs: distinguish capture core tests from helper builds Tested: npm run docs:check; git diff --check; verified Package.swift target dependencies Confidence: high Scope-risk: narrow --- .harness/docs/git-workflow.md | 4 ++-- AGENTS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.harness/docs/git-workflow.md b/.harness/docs/git-workflow.md index e522df3ca2..d32ff8d3b1 100644 --- a/.harness/docs/git-workflow.md +++ b/.harness/docs/git-workflow.md @@ -29,9 +29,9 @@ CI runs on every PR to `main`, `feat/ai-edition`, `release/**` and `integration/ - `npm run docs:check` - `npx vite build` (renderer build smoke) - `cargo test` / `cargo check` for the compositor on macOS, Windows and Linux -- `swift test` and a release build of both macOS capture helpers +- `swift test` for the capture core and a release build of both macOS helpers -All must be green before merge. The macOS helpers have compile and unit-test coverage, but CI does not exercise real capture, permissions or devices. Manual smoke tests on the affected platforms are still required for native changes; note them in the PR description. See the [CI job inventory](../../technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci) for the exact checks and runners. +All must be green before merge. The capture core has unit-test coverage, and both macOS helpers have compile coverage, but CI does not exercise real capture, permissions or devices. Manual smoke tests on the affected platforms are still required for native changes; note them in the PR description. See the [CI job inventory](../../technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci) for the exact checks and runners. ## Pull request flow diff --git a/AGENTS.md b/AGENTS.md index 0f53b8cfc5..ceea69bb61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -171,7 +171,7 @@ The one rule to know before you merge anything: **there is one release branch pe ## Specialized notes -- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI tests and builds the macOS Swift helpers and checks the compositor on macOS, Windows and Linux. These checks do not exercise real capture, permissions or devices; manual smoke tests on the affected platforms are still required for native changes. See [CI coverage](technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci). +- **Native capture is platform-fragile**: macOS uses ScreenCaptureKit (Swift), Windows uses WGC (C++/Win32). CI unit-tests the Swift capture core, builds both macOS helpers and checks the compositor on macOS, Windows and Linux. These checks do not exercise real capture, permissions or devices; manual smoke tests on the affected platforms are still required for native changes. See [CI coverage](technical-documentation/engineering/ci-workflows.md#tier-1-application-and-documentation-ci). - **Rendering is native**: the Rust compositor in `crates/compositor/` renders the editor preview and every export, MP4 and GIF. It runs on Direct3D 11 on Windows, Metal on macOS and wgpu on Linux, with a CPU fallback on Windows and Linux. The renderer only paints the preview frames it pulls onto a ``. Details: `technical-documentation/README.md`, then `architecture/native-compositor.md`. - **i18n**: 15 locales in `src/i18n/locales//` (e.g. `src/i18n/locales/en/settings.json`). The `i18n:check` script validates them — run it after touching translation files. - **Website i18n** is separate: 8 locales under `website/i18n/`. After changing an English doc, page or `` string in `website/`, follow `website/i18n/TRANSLATING.md` ("Keeping translations up to date"); `npm run i18n:check` in `website/` lists what is behind.