From cb79a00aebcc838c9cb785c0ef8c5dca679921a6 Mon Sep 17 00:00:00 2001 From: Gordon Lam <73506701+yeelam-gordon@users.noreply.github.com> Date: Tue, 9 Sep 2025 01:48:43 -0700 Subject: [PATCH] Add the first copilot-instructions.md (#41518) This pull request introduces concise, area-specific contributor guides for the PowerToys repository. Each major code area now has its own instructions file, clarifying scope, coding guidelines, and acceptance criteria. This helps ensure consistency, reduces onboarding friction, and sets clear expectations for contributors. Reference doc: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions New contributor guides added: **General/Top-level guidance** - Added `.github/copilot-instructions.md` as a concise, top-level guide for AI-driven changes, including a repo map, build/test workflow, PR expectations, and quick reference checklists. **Area-specific instructions** - Added `src/common/common.instructions.md` for shared libraries, covering ABI stability, logging, performance, and dependency policies. - Added `src/runner/runner.instructions.md` for the Runner/tray host, detailing module management, IPC contract alignment, startup performance, and elevation/update logic. - Added `src/settings-ui/settings-ui.instructions.md` for the Settings UI, with guidance on schema changes, IPC contract sync, UI responsiveness, and style reuse. --- .github/copilot-instructions.md | 43 +++++++++++++++++++++ src/common/common.instructions.md | 16 ++++++++ src/runner/runner.instructions.md | 17 ++++++++ src/settings-ui/settings-ui.instructions.md | 17 ++++++++ 4 files changed, 93 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 src/common/common.instructions.md create mode 100644 src/runner/runner.instructions.md create mode 100644 src/settings-ui/settings-ui.instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..092df9fc17 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,43 @@ +# PowerToys – Copilot guide (concise) + +This is the top-level guide for AI changes. Keep edits small, follow existing patterns, and cite exact paths in PRs. + +Repo map (1‑line per area) +- Core apps: `src/runner/**` (tray/loader), `src/settings-ui/**` (Settings app) +- Shared libs: `src/common/**` +- Modules: `src/modules/*` (one per utility; Command Palette in `src/modules/cmdpal/**`) +- Build tools/docs: `tools/**`, `doc/devdocs/**` + +Build and test (defaults) +- Prerequisites: Visual Studio 2022 17.4+, minimal Windows 10 1803+. +- Build discipline: + - One terminal per operation (build → test). Don’t switch/open new ones mid-flow. + - After making changes, `cd` to the project folder that changed (`.csproj`/`.vcxproj`). + - Use script(s) to build, synchronously block and wait in foreground for it to finish: `tools/build/build.ps1|.cmd` (current folder), `build-essentials.*` (once per brand new build for missing nuget packages) + - Treat build **exit code 0** as success; any non-zero exit code is a failure, have Copilot read the errors log in the build folder (e.g., `build.*.*.errors.log`) and surface problems. + - Don’t start tests or launch Runner until the previous step succeeded. +- Tests (fast + targeted): + - Find the test project by product code prefix (e.g., FancyZones, AdvancedPaste). Look for a sibling folder or 1–2 levels up named like `*UnitTests` or `*UITests`. + - Build the test project, wait for **exit**, then run only those tests via VS Test Explorer or `vstest.console.exe` with filters. Avoid `dotnet test` in this repo. + - Add/adjust tests when changing behavior; if skipped, state why (e.g., comment-only, string rename). + +Pull requests (expectations) +- Atomic: one logical change; no drive‑by refactors. +- Describe: problem / approach / risk / test evidence. +- List: touched paths if not obvious. + +When to ask for clarification +- Ambiguous spec after scanning relevant docs (see below). +- Cross-module impact (shared enum/struct) not clear. +- Security / elevation / installer changes. + +Logging (use existing stacks) +- C++: `src/common/logger/**` (`Logger::info|warn|error|debug`). Keep hot paths quiet (hooks, tight loops). +- C#: `ManagedCommon.Logger` (`LogInfo|LogWarning|LogError|LogDebug|LogTrace`). Some UIs use injected `ILogger` via `LoggerInstance.Logger`. + +Docs to consult +- `tools/build/BUILD-GUIDELINES.md` +- `doc/devdocs/core/architecture.md`, `doc/devdocs/core/runner.md`, `doc/devdocs/core/settings/readme.md`, `doc/devdocs/modules/readme.md` + +Done checklist (self review before finishing) +- Build clean? Tests updated/passed? No unintended formatting? Any new dependency? Documented skips? \ No newline at end of file diff --git a/src/common/common.instructions.md b/src/common/common.instructions.md new file mode 100644 index 0000000000..f9bde1d388 --- /dev/null +++ b/src/common/common.instructions.md @@ -0,0 +1,16 @@ +--- +applyTo: "**/*.cs,**/*.cpp,**/*.c,**/*.h,**/*.hpp" +--- +# Common – shared libraries guidance (concise) + +Scope +- Logging, IPC, settings, DPI, telemetry, utilities consumed by multiple modules. + +Guidelines +- Avoid breaking public headers/APIs; if changed, search & update all callers. +- Coordinate ABI-impacting struct/class layout changes; keep binary compatibility. +- Watch perf in hot paths (hooks, timers, serialization); avoid avoidable allocations. +- Ask before adding third‑party deps or changing serialization formats. + +Acceptance +- No unintended ABI breaks, no noisy logs, new non-obvious symbols briefly commented. \ No newline at end of file diff --git a/src/runner/runner.instructions.md b/src/runner/runner.instructions.md new file mode 100644 index 0000000000..9dace8aae3 --- /dev/null +++ b/src/runner/runner.instructions.md @@ -0,0 +1,17 @@ +--- +applyTo: "**/*.cpp,**/*.c,**/*.h,**/*.hpp,**/*.rc" +--- +# Runner – tray / host process guidance + +Scope +- Module bootstrap, hotkey management, settings bridge, update/elevation handling. + +Guidelines +- If IPC/JSON contracts change, mirror updates in `src/settings-ui/**`. +- Keep module discovery in `src/runner/main.cpp` in sync when adding/removing modules. +- Keep startup lean: avoid blocking/network calls in early init path. +- Preserve GPO & elevation behaviors; confirm no regression in policy handling. +- Ask before modifying update workflow or elevation logic. + +Acceptance +- Stable startup, consistent contracts, no unnecessary logging noise. \ No newline at end of file diff --git a/src/settings-ui/settings-ui.instructions.md b/src/settings-ui/settings-ui.instructions.md new file mode 100644 index 0000000000..cf527b69f0 --- /dev/null +++ b/src/settings-ui/settings-ui.instructions.md @@ -0,0 +1,17 @@ +--- +applyTo: "**/*.cs,**/*.xaml" +--- +# Settings UI – configuration app guidance + +Scope +- WinUI/WPF UI, communicates with Runner over named pipes; manages persisted settings schema. + +Guidelines +- Don’t break settings schema silently; add migration when shape changes. +- If IPC/JSON contracts change, align with `src/runner/**` implementation. +- Keep UI responsive: marshal to UI thread for UI-bound operations. +- Reuse existing styles/resources; avoid duplicate theme keys. +- Add/adjust migration or serialization tests when changing persisted settings. + +Acceptance +- Schema integrity preserved, responsive UI, consistent contracts, no style duplication. \ No newline at end of file