1  # PowerToys Development Guidelines
  2  
  3  ## Using Open Source Packages and Libraries
  4  
  5  ### License Considerations
  6  - MIT license is generally acceptable for inclusion in the project
  7  - For any license other than MIT, double check with the PM team
  8  - All external packages or projects must be mentioned in the `notice.md` file
  9  - Even if a license permits free use, it's better to verify with the team
 10  
 11  ### Safety and Quality Considerations
 12  - Ensure the code being included is safe to use
 13  - Avoid repositories or packages that are not widely used
 14  - Check for packages with significant downloads/usage and good ratings
 15  - Important because our pipeline signs external DLLs with Microsoft certificate
 16  - Unsafe code signed with Microsoft certificate can cause serious issues
 17  
 18  ## Code Signing
 19  
 20  ### Signing JSON File
 21  - Modifications to the signing JSON file are typically done manually
 22  - When adding new DLLs (internal PowerToys modules or external libraries)
 23  - When the release pipeline fails with a list of unsigned DLLs/executables:
 24    - For PowerToys DLLs, manually add them to the list
 25    - For external DLLs, verify they're safe to sign before including
 26  
 27  ### File Signing Requirements
 28  - All DLLs and executables must be signed
 29  - New files need to be added to the signing configuration
 30  - CI checks if all files are signed
 31  - Even Microsoft-sourced dependencies are signed if they aren't already
 32  
 33  ## Performance Measurement
 34  
 35  - Currently no built-in timers to measure PowerToys startup time
 36  - Startup measurement could be added in the runner:
 37    - At the start of the main method
 38    - After all module interface DLLs are loaded
 39  - Alternative: use profilers or Visual Studio profiler
 40  - Startup currently takes some time due to:
 41    - Approximately 20 module interface DLLs that need to be loaded
 42    - Modules that are started during loading
 43  - No dashboards or dedicated tools for performance measurement
 44  - Uses System.Diagnostics.Stopwatch in code
 45  - Performance data is logged to default PowerToys logs
 46  - Can search logs for stopwatch-related messages to diagnose performance issues
 47  - Some telemetry events contain performance information
 48  
 49  ## Dependency Management
 50  
 51  ### WinRT SDK and CS/WinRT
 52  - Updates to WinRT SDK and CS/WinRT are done periodically
 53  - WinRT SDK often requires higher versions of CS/WinRT or vice versa
 54  - Check for new versions in NuGet.org or Visual Studio's NuGet Package Explorer
 55  - Prefer stable versions over preview versions
 56  - Best practice: Update early in the release cycle to catch potential regressions
 57  
 58  ### WebView2
 59  - Used for components like monotone file preview
 60  - WebView2 version is related to the WebView runtime in Windows
 61  - Previous issues with Windows Update installing new WebView runtime versions
 62  - WebView team now includes PowerToys testing in their release cycle
 63  - When updating WebView2:
 64    - Update the version
 65    - Open a PR
 66    - Perform sanity checks on components that use WebView2
 67  
 68  ### General Dependency Update Process
 69  - When updating via Visual Studio, it will automatically update dependencies
 70  - After updates, perform:
 71    - Clean build
 72    - Sanity check that all modules still work
 73    - Open PR with changes
 74  
 75  ## Testing Requirements
 76  
 77  ### Multiple Computers
 78  - **Mouse Without Borders**: Requires multiple physical computers for proper testing
 79    - Testing with VMs is not recommended as it may cause confusion between host and guest mouse input
 80    - At least 2 computers are needed, sometimes testing with 3 is done
 81    - Testing is usually assigned to team members known to have multiple computers
 82  
 83  ### Multiple Monitors
 84  - Some utilities require multiple monitors for testing
 85  - At least 2 monitors are recommended
 86  - One monitor should be able to use different DPI settings
 87  
 88  ### Fuzzing Testing
 89  - Security team requires fuzzing testing for modules that handle file I/O or user input
 90  - Helps identify vulnerabilities and bugs by feeding random, invalid, or unexpected data
 91  - PowerToys integrates with Microsoft's OneFuzz service for automated testing
 92  - Both .NET (C#) and C++ modules have different fuzzing implementation approaches
 93  - New modules handling file I/O or user input should implement fuzzing tests
 94  - For detailed setup instructions, see [Fuzzing Testing in PowerToys](../tools/fuzzingtesting.md)
 95  
 96  ### Testing Process
 97  - For reporting bugs during the release candidate testing:
 98    1. Discuss in team chat
 99    2. Determine if it's a regression (check if bug exists in previous version)
100    3. Check if an issue is already open
101    4. Open a new issue if needed
102    5. Decide on criticality for the release (if regression)
103  
104  ### Release Testing
105  - Team follows a release checklist
106  - Includes testing for WinGet configuration
107  - Sign-off process:
108    - Teams sign off on modules independently
109    - Regressions found in first release candidates lead to PRs
110    - Second release candidate verified fixes
111    - Command Palette needs separate sign-off
112    - Final verification ensures modules don't crash with Command Palette integration
113  
114  ## PR Management and Release Process
115  
116  ### PR Review Process
117  - PM team typically tags PRs with "need review" 
118  - Small fixes from community that don't change much are usually accepted
119  - PM team adds tags like "need review" to highlight PRs
120  - PMs set priorities (sometimes using "info.90" tags)
121  - PMs decide which PRs to prioritize
122  - Team members can help get PRs merged when there's flexibility
123  
124  ### PR Approval Requirements
125  - PRs need approval from code owners before merging
126  - New team members can approve PRs but final approval comes from code owners
127  
128  ### PR Priority Handling
129  - Old PRs sometimes "slip through the cracks" if not high priority
130  - PMs tag important PRs with "priority one" to indicate they should be included in release
131  - Draft PRs are generally not prioritized
132  
133  ### Specific PR Types
134  - CI-related PRs need review and code owner approval
135  - Feature additions (like GPO support) need PM decision on whether the feature is wanted
136  - Bug fixes related to Watson errors sometimes don't have corresponding issue links
137  - Command Palette is considered high priority for the upcoming release
138  
139  ## Project Management Notes
140  
141  - Be careful about not merging incomplete features into main
142  - Feature branches should be used for work in progress
143  - PRs touching installer files should be carefully reviewed
144  - Incomplete features should not be merged into main
145  - Use feature branches (feature/name-of-feature) for work-in-progress features
146  - Only merge to main when complete or behind experimentation flags