mirror of
https://github.com/microsoft/PowerToys.git
synced 2025-12-16 11:48:06 +01:00
[DevDocs] More content and restructure (#40165)
## Summary of the Pull Request Accumulated information from internal transition about the modules development, and reworked it to be added in dev docs. Also the dev docs intself was restructured to be more organized. New pages was verified by transition team. ## PR Checklist - [x] **Dev docs:** Added/updated --------- Co-authored-by: Zhaopeng Wang (from Dev Box) <zhaopengwang@microsoft.com> Co-authored-by: Hao Liu <liuhao3418@gmail.com> Co-authored-by: Peiyao Zhao <105847726+zhaopy536@users.noreply.github.com> Co-authored-by: Mengyuan <162882040+chenmy77@users.noreply.github.com> Co-authored-by: zhaopeng wang <33367956+wang563681252@users.noreply.github.com> Co-authored-by: Jaylyn Barbee <51131738+Jaylyn-Barbee@users.noreply.github.com>
This commit is contained in:
Gleb Khmyznikov
125
doc/devdocs/processes/gpo.md
Normal file
125
doc/devdocs/processes/gpo.md
Normal file
@@ -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.
|
||||
183
doc/devdocs/processes/release-process.md
Normal file
183
doc/devdocs/processes/release-process.md
Normal file
@@ -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 higher 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
|
||||
111
doc/devdocs/processes/update-process.md
Normal file
111
doc/devdocs/processes/update-process.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user