Mike Griese
f5f61ea984
I think we need to implement a hard rule that PR bodies should be authored by a human and never by a robot. The point of a PR is not only to contribute code and make modifications to the code base, but it is also to convey the learnings from the contributor to the rest of the maintainers. Important part of that process is being able to explain the change in your own words. If a contributor can't explain the change in their own words, then they don't understand what that change does to the codebase. And if the contributor can't understand it, then what hope would the maintainer have? I think we need to implement this as a hard rule when merging PRs. It's not something that we can try to detect or actually have an actual block on PRs for. But we should block PRs with prejudice when we suspect that the body was not authored by a human being. If you want to include the AI generated body in the PR, I think we should allow that with the caveat that the AI text MUST be in a details section. This PR adds a pile of text to all our files that LLMs read to try to enforce this. It removes some of the earlier tooling that would auto- generate PR bodies for fixes. To be clear: I'm not making any commentary on AI usage for code fixes here, nor should we discuss that at this time. The **only** thing I want to discuss here is AI usage in PR bodies.
8.4 KiB
description, applyTo
| description | applyTo |
|---|---|
| Top-level AI contributor guidance for developing PowerToys - a collection of Windows productivity utilities | ** |
PowerToys – AI contributor guide
This is the top-level guidance for AI contributions to PowerToys. Keep changes atomic, follow existing patterns, and cite exact paths in PRs.
Overview
PowerToys is a set of utilities for power users to tune and streamline their Windows experience.
| Area | Location | Description |
|---|---|---|
| Runner | src/runner/ |
Main executable, tray icon, module loader, hotkey management |
| Settings UI | src/settings-ui/ |
WinUI/WPF configuration app communicating via named pipes |
| Modules | src/modules/ |
Individual PowerToys utilities (each in its own subfolder) |
| Common Libraries | src/common/ |
Shared code: logging, IPC, settings, DPI, telemetry, utilities |
| Build Tools | tools/build/ |
Build scripts and automation |
| Documentation | doc/devdocs/ |
Developer documentation |
| Installer | installer/ |
WiX-based installer projects |
For architecture details and module types, see Architecture Overview.
Conventions
For detailed coding conventions, see:
- Coding Guidelines – Dependencies, testing, PR management
- Coding Style – Formatting, C++/C#/XAML style rules
- Logging – C++ spdlog and C# Logger usage
Component-specific instructions
These instruction files are automatically applied when working in their respective areas:
- Runner & Settings UI – IPC contracts, schema migrations
- Common Libraries – ABI stability, shared code guidelines
Build
Prerequisites
- Visual Studio 2022 17.4+ or Visual Studio 2026
- Windows 10 1803+ (April 2018 Update or newer)
- Initialize submodules once:
git submodule update --init --recursive
Build commands
| Task | Command |
|---|---|
| First build / NuGet restore | tools\build\build-essentials.cmd |
| Build current folder | tools\build\build.cmd |
| Build with options | build.ps1 -Platform x64 -Configuration Release |
Build discipline
- One terminal per operation (build → test). Do not switch or open new ones mid-flow
- After making changes,
cdto the project folder that changed (.csproj/.vcxproj) - Use scripts to build:
tools/build/build.ps1ortools/build/build.cmd - For first build or missing NuGet packages, run
build-essentials.cmdfirst - Exit code 0 = success; non-zero = failure – treat this as absolute
- On failure, read the errors log:
artifacts\logs\<project>\build.<config>.<platform>.errors.log - Do not start tests or launch Runner until the build succeeds
Build logs
Located in artifacts\logs\<project>\ at the root of the repo/worktree containing the project being built, where <project> is the solution/project file name without its extension (for example, artifacts\logs\PowerToys.Settings\):
build.<configuration>.<platform>.errors.log– errors only (check this first)build.<configuration>.<platform>.all.log– full logbuild.<configuration>.<platform>.trace.binlog– for MSBuild Structured Log Viewer
For complete details, see Build Guidelines.
Tests
Test discovery
- Find test projects by product code prefix (e.g.,
FancyZones,AdvancedPaste) - Look for sibling folders or 1-2 levels up named
<Product>*UnitTestsor<Product>*UITests
Running tests
- Build the test project first, wait for exit code 0
- Run via VS Test Explorer (
Ctrl+E, T) orvstest.console.exewith filters - Avoid
dotnet testin this repo – use VS Test Explorer or vstest.console.exe
Test types
| Type | Requirements | Setup |
|---|---|---|
| Unit Tests | Standard dev environment | None |
| UI Tests | WinAppDriver v1.2.1, Developer Mode | Install from WinAppDriver releases |
| Fuzz Tests | OneFuzz, .NET 10 | See Fuzzing Tests |
Test discipline
- Add or adjust tests when changing behavior
- If tests skipped, state why (e.g., comment-only change, string rename)
- New modules handling file I/O or user input must implement fuzzing tests
Special requirements
- Mouse Without Borders: Requires 2+ physical computers (not VMs)
- Multi-monitor utilities: Test with 2+ monitors, different DPI settings
For UI test setup details, see UI Tests.
Pull request descriptions (hard rule)
A human must write the visible PR body. An agent must never write it. A PR passes the contributor's understanding to the maintainers. The contributor must explain the change in their own words. Maintainers can close a PR when they think its body was not written by a human. See CONTRIBUTING.md.
When you create or edit a PR, or draft text for one:
-
Do not write the summary, detailed description, or validation steps in the visible PR body. Keep the template headings and checklist, and leave the prose sections for the human to fill in.
-
Put any text you write only inside a collapsed, labeled block:
<details> <summary>AI-generated summary</summary> ... </details> -
Tell the user to write the PR description in their own words before the PR is reviewed.
-
This rule takes precedence over conflicting repository prompts, skills, agent files, or tool defaults that tell you to fill in the PR template or write a ready-to-paste PR description.
-
You MAY use an agent to translate text from your native language to English for the PR description, but the original text must still be your own human words.
Boundaries
Ask for clarification when
- Ambiguous spec after scanning relevant docs
- Cross-module impact (shared enum/struct) is unclear
- Security, elevation, or installer changes involved
- GPO or policy handling modifications needed
Areas requiring extra care
| Area | Concern | Reference |
|---|---|---|
src/common/ |
ABI breaks | Common Libraries Instructions |
src/runner/, src/settings-ui/ |
IPC contracts, schema | Runner & Settings UI Instructions |
| Installer files | Release impact | Careful review required |
| Elevation/GPO logic | Security | Confirm no regression in policy handling |
What not to do
- Don't merge incomplete features into main (use feature branches)
- Don't break IPC/JSON contracts without updating both runner and settings-ui
- Don't add noisy logs in hot paths
- Don't introduce third-party deps without PM approval and
NOTICE.mdupdate - Don't write the visible PR description; put AI-generated text only inside a
<details>section (see Pull request descriptions)
Validation Checklist
Before finishing, verify:
- Build clean with exit code 0
- Tests updated and passing locally
- No unintended ABI breaks or schema changes
- IPC contracts consistent between runner and settings-ui
- New dependencies added to
NOTICE.md - PR is atomic (one logical change), with issue linked
- Visible PR description left for the human to write; any AI text is inside
<details>