chore: import upstream snapshot with attribution

doc/devdocs/processes/gpo.md

@@ -0,0 +1,125 @@
+# PowerToys GPO (Group Policy Objects) Implementation
+
+Group Policy Objects (GPOs) allow system administrators to control PowerToys settings across an organization. This document describes how GPOs are implemented in PowerToys.
+
+## GPO Overview
+
+GPO policies allow system administrators to control PowerToys settings. PowerToys ships GPO files as part of the release zip, not installed directly.
+
+## GPO File Structure
+
+### ADMX File
+- Contains policy definitions
+- Defines which versions support each policy
+- Sets up folder structure
+- Defines each policy with:
+  - Name
+  - Class (user scope or machine scope)
+  - Description
+  - Registry location where policy is stored
+  - Enabled/disabled values
+
+### ADML File
+- Contains localized strings for the ADMX file
+- Contains revision number that must be updated when changes are made
+- Stores strings for:
+  - Folder names
+  - Version definitions
+  - Policy descriptions and titles
+- Currently only ships English US version (no localization story yet)
+
+## Installation Process
+
+- Files need to be placed in: `C:\Windows\PolicyDefinitions\`
+- ADMX file goes in the root folder
+- ADML file goes in the language subfolder (e.g., en-US)
+- After installation, policies appear in the Group Policy Editor (gpedit.msc)
+
+## Registry Implementation
+
+- Policies are stored as registry values
+- Location: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys` or `HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys`
+- Machine scope takes precedence over user scope
+- Policy states:
+  - Enabled: Registry value set to 1
+  - Disabled: Registry value set to 0
+  - Not Configured: Registry value does not exist
+
+## Code Integration
+
+### Common Files
+- Policy keys defined in `common\utils\GPO.h`
+- Contains functions to read registry values and get configured values
+- WinRT C++ adapter created for C# applications to access GPO settings
+
+### WPF Applications
+- WPF applications cannot directly load WinRT C++ projects
+- Additional library created to allow WPF applications to access GPO values
+
+### Module Interface
+- Each module must implement policy checking in its interface
+- Runner checks this to determine if module should be started or not
+
+## UI Implementation
+
+- When a policy disables a utility:
+  - UI is locked (cannot be enabled)
+  - Settings page shows a lock icon
+  - Dashboard hides the module button
+  - If user tries to start the executable directly, it exits and logs a message
+
+## Types of GPO Policies
+
+### Basic Module Enable/Disable Policy
+- Most common type
+- Controls whether a module can be enabled or disabled
+- Shared description text for these policies
+
+### Configuration Policies
+- Example: Run at startup setting
+- Controls specific settings rather than enabling/disabling modules
+- Custom description text explaining what happens when enabled/disabled/not configured
+
+### Machine-Scope Only Policies
+- Example: Mouse Without Borders service mode
+- Only makes sense at machine level (not user level)
+- Restricts functionality that requires elevated permissions
+
+## Steps to Add a New Policy
+
+1. Update ADMX file:
+   - Increase revision number
+   - Add supported version definition
+   - Define the policy with registry location
+
+2. Update ADML file:
+   - Increase revision number
+   - Add strings for version, title, description
+
+3. Update code:
+   - Add to GPO.h
+   - Add to GPO wrapper for C# access
+   - Update module interface
+   - Modify settings UI to show lock when policy applied
+   - Add checks in executable to prevent direct launching
+   - Update dashboard helper to respect policy
+
+4. Add to bug report tool to capture policy state
+
+## Update-Related GPO Settings
+
+- `disable automatic update download` - Prevents automatic downloading
+- `disable new update toast` - Controls if toast notifications are shown
+- `suspend new update toast` - Suspends toast notifications for 2 minor releases
+
+## Testing GPO Settings
+
+To test GPO settings locally:
+
+1. Run `regedit` as administrator
+2. Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\PowerToys`
+3. Create a new DWORD value with the name of the policy
+4. Set the value to 0 (disabled) or 1 (enabled)
+5. Restart PowerToys to see the effect
+
+For user-scope policies, use `HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\PowerToys` instead.

doc/devdocs/processes/release-process.md

@@ -0,0 +1,183 @@
+# PowerToys Release Process
+
+This document outlines the process for preparing and publishing PowerToys releases.
+
+## Release Preparation
+
+### Branch Management
+1. Sync commits from main branch to stable branch
+   - Usually sync current main to stable
+   - For hotfixes: might need to cherry-pick specific commits
+
+2. Start release build from the stable branch
+   - Use pipelines to build
+   - Set version number (e.g., 0.89.0)
+   - Build for both x64 and ARM64
+   - Build time: ~1-2 hours (signing can take extra time)
+   - Build can be flaky, might need multiple attempts
+
+3. Artifacts from the build:
+   - ARM64 release files
+     - PowerToys setup for ARM64 (machine setup)
+     - User setup
+   - X64 release files
+     - PowerToys setup for x64 (machine setup)
+     - User setup
+   - GPO files (same for both architectures)
+   - Hash files for verification
+   - Symbols that are shipped with every release
+
+### Versioning
+- Uses semantic versioning: `MAJOR.MINOR.PATCH`
+- MINOR version increases with regular releases (e.g., 0.89.0)
+- PATCH version increases for hotfixes (e.g., 0.87.0 → 0.87.1)
+- Each release version must be greater than the previous one for proper updating
+
+## Testing Process
+
+### Release Candidate Testing
+1. Fully test the builds using a checklist
+   - Manual tests for each release
+   - Each test item should be verified by at least 2 people
+   - Test on both x64 and ARM64 machines
+   - Every module is tested by at least two people
+   - New team members typically take 2 days for complete testing
+   - Experienced team members complete testing in less than a day (~2 hours for 1/3 of tests)
+
+2. For subsequent Release Candidates:
+   - Full retesting of modules with changes
+   - Verifying specific fixes
+   - Sanity checking all utilities (ensuring no startup crashes)
+
+3. If regressions found:
+   - Fix issues
+   - Return to step 1 (sync fixes to stable and build again)
+
+### Testing Workflow
+1. Team divides the test checklist among members
+2. Each member performs assigned tests
+3. Members report any issues found
+4. Team assesses if issues are release blockers
+5. Team confirms testing completion before proceeding
+
+### Reporting Bugs During Testing
+1. Discuss in team chat
+2. Determine if it's a regression (check if bug exists in previous version)
+3. Check if an issue is already open
+4. Open a new issue if needed
+5. Decide on criticality for the release (if regression)
+
+### Sign-off Process
+- Teams sign off on modules independently
+- Regressions found in first release candidates lead to PRs
+- Second release candidate verified fixes
+- Final verification ensures modules don't crash with new features
+
+## Documentation and Changelog
+
+### README Updates
+1. Create PR with README updates for the release:
+   - Add new utilities to the list if applicable
+   - Update milestones
+   - Update expected download links
+   - Upload new hashes
+   - Update version and month
+   - Write highlights of important changes
+   - Thank open source contributors
+     - Don't thank internal team members or Microsoft employees assigned to the project
+     - Exception: thank external helpers like Niels (UI contributions)
+
+### Changelog Creation
+- Changelog PR should be created several days before release
+- Community members need time to comment and request changes
+- Project managers need time to review and clean up
+- When team testing is set, either tests are done or changelog is created right away
+
+### Changelog Structure
+- **General section**: 
+  - Issues/fixes not related to specific modules
+  - User-visible changes
+  - Important package updates (like .NET packages)
+  - Fixes that affect end users
+
+- **Development section**:
+  - CI-related changes
+  - Changes not visible to end users
+  - Performance improvements internal to the system
+  - Refactoring changes
+  - Logger updates and other developer-focused improvements
+
+### Formatting Notes
+- Special attention needed for "highlights" section
+- Different format is required for highlights in README versus release notes
+- Must follow the exact same pattern/format for proper processing
+- PowerToys pulls "What's New" information from the GitHub API
+  - Gets changelog from the latest 5 releases
+  - Format must be consistent for the PowerToys code to properly process it
+  - Code behind will delete everything between certain markers (installer hashes and highlights)
+
+### Documentation Changes
+- Public docs appear on the web
+- Changes happen in the Microsoft Docs repo: microsoft/windows-dev-docs
+- For help with docs, contact Alvin Ashcraft from Microsoft
+- Content automatically appears on learn.microsoft.com when PR is merged
+
+## GitHub Release Process
+
+### Creating the Release
+1. Ask the project management team to start a GitHub release draft
+   - Draft should target stable branch
+   - Use proper version format (e.g., V 0.89.0)
+   - Set title using same format (e.g., "Release V 0.89.0")
+
+2. After testing is complete:
+   - Pick up the hashes from artifacts
+   - Apply changelog
+   - Fill in release notes
+   - Upload binaries
+     - GPO files
+     - Setup files
+     - ZIP files with symbols
+   - Only press "Save Draft", don't publish yet
+
+3. Final verification:
+   - Download every file from the draft
+   - Check that ZIPs can be unzipped
+   - Verify hashes match expectations
+   - Tell the project management team the release is good to go
+   - They will handle the actual publishing
+
+### Post-Release Actions
+- GitHub Actions automatically trigger:
+  - Store submission
+  - WinGet submission
+- Monitor these actions to ensure they complete successfully
+- If something fails, action may need to be taken
+
+## Release Decision Making
+
+### Timing Considerations
+- Release owner should coordinate with project managers
+- Project managers have high-level view of what should be included in the release
+- Use the "in for .XX" tag to identify PRs that should be included
+- If a key feature isn't ready, discuss with PMs whether to delay the release
+
+### Release Coordination
+- Release coordination requires good communication with domain feature owners
+- Coordination needed with project managers and key feature developers
+- Release candidate can only be done once key features have been merged
+- Need to ensure all critical fixes are included before the release candidate
+
+## Special Cases
+
+### Hotfix Process
+- For critical issues found after release
+- Create a hotfix branch from the stable branch
+- Cherry-pick only essential fixes
+- Increment the PATCH version (e.g., 0.87.0 → 0.87.1)
+- Follow the standard release process but with limited testing scope
+
+### Community Testing
+- Community members generally don't have access to draft builds
+- Exception: Some Microsoft MVPs sometimes test ARM64 builds
+- If providing builds to community members, use a different version number (e.g., 0.1.x) to avoid installer conflicts

doc/devdocs/processes/update-process.md

@@ -0,0 +1,111 @@
+# PowerToys Update Process
+
+This document describes how the PowerToys update mechanism works.
+
+## Key Files
+
+- `updating.h` and `updating.cpp` in common - Contains code for handling updates and helper functions
+- `update_state.h` and `update_state.cpp` - Handles loading and saving of update state
+
+## Update Process
+
+### Version Detection
+- Uses GitHub API to get the latest version information
+- API returns JSON with release information including version and assets
+- Checks asset names to find the correct installer based on:
+  - Architecture (ARM64 or X64)
+  - Installation scope (user or machine)
+
+### Installation Scope
+- Differentiates between user installer and machine installer
+- Different patterns are defined to distinguish between the two scopes
+- Both have different upgrade codes
+
+### Update State
+- State is stored in a local file
+- Contains information like:
+  - Current update state
+  - Release page URL
+  - Last time check was performed
+  - Whether a new version is available
+  - Whether installer is already downloaded
+
+### Update Checking
+- Manual check: When user clicks "Check for Updates" in settings
+- Automatic check: Periodic update worker runs periodically to check for updates
+- Update state is saved to: `%LOCALAPPDATA%\Microsoft\PowerToys\update_state.json`
+
+### Update Process Flow
+1. Check current version against latest version from GitHub
+2. If newer version exists:
+   - Check metered connection settings
+   - Check if automatic updates are enabled
+   - Check GPO settings
+3. Process new version:
+   - Check if installer is already downloaded
+   - Clean up old installer files
+   - Download new installer if needed
+4. Notify user via toast notification
+
+### PowerToys Updater
+- `PowerToysUpdate.exe` - Executable shipped with installer
+- Handles downloading and running the installer
+- Called when user clicks the update toast notification
+- Downloads the installer if not already downloaded
+
+### Version Numbering
+- Semantic versioning: `MAJOR.MINOR.PATCH`
+- MINOR version increases with regular releases (e.g., 0.89.0)
+- PATCH version increases for hotfixes (e.g., 0.87.0 → 0.87.1)
+
+### Installer Details
+- Uses WiX bootstrapper
+- Defines upgrade codes for per-user and per-machine installations
+- These codes must remain consistent for proper updating
+
+## GPO Update Settings
+
+PowerToys respects Group Policy settings for controlling updates:
+
+- `disable automatic update download` - Prevents automatic downloading
+- `disable new update toast` - Controls if toast notifications are shown
+- `suspend new update toast` - Suspends toast notifications for 2 minor releases
+
+## User Settings
+
+Users can control update behavior through the PowerToys settings:
+
+- Automatic update downloads can be enabled/disabled
+- Download and install updates automatically on metered connections
+
+## Update Notification
+
+When a new update is available:
+1. Toast notification appears in the Windows Action Center
+2. Clicking the notification starts the update process
+3. The updater downloads the installer (if not already downloaded)
+4. The installer runs with appropriate command-line arguments
+
+## Debugging Tips
+
+### Testing Update Detection
+- To force an update check, modify the timestamp in the update state file to an earlier date
+- Exit PowerToys, modify the file, then restart PowerToys
+
+### Common Issues
+- Permission issues can prevent downloading updates
+- Network connectivity problems may interrupt downloads
+- Group Policy settings may block updates
+- Installer may fail if the application is running
+
+### Update Logs
+- Check PowerToys logs for update-related messages
+- `%LOCALAPPDATA%\Microsoft\PowerToys\Logs\PowerToys-*.log`
+- Look for entries related to update checking and downloading
+
+## Rollout Considerations
+
+- Updates are made available to all users simultaneously
+- No staged rollout mechanism is currently implemented
+- Critical issues discovered after release require a hotfix
+- See [Release Process](release-process.md) for details on creating hotfixes