Contributing to PowerToys

Learn how to contribute code, documentation, and translations to Microsoft PowerToys

Overview

PowerToys welcomes contributions from the community! Whether you’re fixing bugs, adding features, improving documentation, or helping with translations, your contributions make PowerToys better for everyone.

Before you start contributing, please read this guide to understand our process and expectations.

Getting Started

Before You Begin

Please follow this important rule to ensure efficient collaboration:

If you have a question, think you’ve discovered an issue, or would like to propose a new feature, please find/file an issue BEFORE starting work to fix/implement it.

This helps:

• Avoid duplicate work
• Ensure alignment with project goals
• Get early feedback on your approach
• Prevent wasted effort

Finding Issues to Work On

1. Browse existing issues: Check the GitHub issues page
2. Look for “Help Wanted” label: Visit Issues labeled Help Wanted
3. Comment before starting: Post on the “Would you like to contribute to PowerToys?” thread

Indicating Interest

To show which issues are important to you:

• Click the [+😊] button and the 👍 icon on the issue
• Avoid comments like “+1” or “me too” (they create noise)

Types of Contributions

Code Contributions

Contribute bug fixes, new features, or improvements to existing utilities.

Process:

1. File or find an issue describing the problem
2. Discuss the approach with the team
3. Get approval before writing code
4. Submit a pull request

Documentation

Help improve guides, tutorials, and API documentation.

What you can do:

• Fix typos and clarify existing docs
• Add examples and tutorials
• Improve developer documentation
• Update outdated information

Translations

Localization is handled exclusively by Microsoft’s internal localization team. Community PRs for translations are not accepted.

If you find translation issues:

1. File an issue using the translation issue template
2. Include the incorrect text and suggested correction
3. Specify the language and utility affected

Development Setup

Prerequisites

• Operating System: Windows 10 April 2018 Update (version 1803) or newer
• Visual Studio: Visual Studio 2026 (recommended) or Visual Studio 2022 17.4+
• Required Workloads:
  • Desktop Development with C++
  • WinUI application development
  • .NET desktop development
  • Windows 10 SDK (10.0.22621.0)
  • Windows 11 SDK (10.0.26100.3916)
• .NET 8 SDK
• Long paths enabled in Windows

You can automatically install Visual Studio with all required workloads using WinGet:

winget configure .config\configuration.winget

Pick the configuration file matching your VS edition (e.g., configuration.vsProfessional.winget).

Setting Up Your Development Environment

1. Fork and Clone

   1. Fork the PowerToys repository on GitHub
   2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/PowerToys.git
   cd PowerToys
   
2. Run Setup Script

   Run the automated setup script (recommended):

   .\tools\build\setup-dev-environment.ps1
   

   This script will:

   • Enable Windows long path support (requires admin)
   • Enable Windows Developer Mode (requires admin)
   • Install required Visual Studio components
   • Initialize git submodules
3. Manual Setup (Alternative)

   If you prefer manual setup:

   1. Open PowerToys.slnx in Visual Studio
   2. Install extra components if prompted
   3. Initialize submodules:

   git submodule update --init --recursive
   

Building PowerToys

Using Visual Studio

1. Open PowerToys.slnx in Visual Studio
2. Select Release or Debug from the Solution Configuration dropdown
3. Press Ctrl+Shift+B or select Build > Build Solution
4. Find binaries in x64\Release\ or x64\Debug\

Some modules (PowerRename, ImageResizer, File Explorer extensions) require building and installing the full installer to function properly.

Using Command Line

PowerToys provides build scripts in tools\build\:

# Build the full solution
.\tools\build\build.ps1

# Build with specific configuration
.\tools\build\build.ps1 -Platform x64 -Configuration Release

# Build only essential projects (faster iteration)
.\tools\build\build-essentials.ps1

# Build everything including installer (Release only)
.\tools\build\build-installer.ps1

Running Tests

1. Build Test Projects

   Build test projects before running them:

   # Navigate to test project directory
   cd src/modules/[module-name]/[module-name].UnitTests
   
   # Build the test project
   ..\..\..\..\tools\build\build.ps1
   
2. Run Tests

   Use Visual Studio Test Explorer:

   • Press Ctrl+E, T to open Test Explorer
   • Click “Run All” to execute tests

   Or use vstest.console.exe from command line

3. UI Tests (Optional)

   For UI testing:

   1. Install WinAppDriver v1.2.1
   2. Enable Developer Mode in Windows Settings
   3. Run UI test projects from Test Explorer

Avoid using dotnet test in this repository. Use Visual Studio Test Explorer or vstest.console.exe instead.

Pull Request Guidelines

Before Submitting a PR

PR Preparation Checklist

1. Ensure Builds Succeed

• Build locally with no errors
• Verify exit code is 0
• Check build.<config>.<platform>.errors.log for issues

2. Test Your Changes

• Add or update unit tests
• Run all relevant tests locally
• Verify functionality manually
• Test on different Windows versions if applicable

3. Follow Coding Standards

• Match existing code style
• Follow coding guidelines
• Add XML documentation for public APIs
• Use meaningful variable names

4. Update Documentation

• Update relevant README files
• Add inline code comments for complex logic
• Update developer docs if needed

PR Template Requirements

When opening a PR, complete the following sections:

• Summary: Brief description of changes
• Closes: Link to related issue(s)
• Communication: Confirm discussion with core contributors
• Tests: Indicate tests added/updated and passing
• Localization: Confirm localizable strings
• Dev docs: Note documentation updates
• Validation: Describe how you tested the changes

PR Process

1. Open Draft PR (Optional)

   For early feedback, open a draft PR with [WIP] or [Draft] in the title.

2. Mark Ready for Review

   When ready for formal review, mark the PR as “Ready for Review”.

3. Respond to Feedback

   Address reviewer comments and update your PR. This may take several cycles.

4. Approval and Merge

   Once approved:

   • PR author merges their own PR
   • For community contributors, reviewer may merge
   • Use “Squash and merge” (default)
   • Use “Rebase and merge” if commits should remain separate

Linking Issues

Use closing keywords in your PR description:

Closes #1234
Fixes #5678

Coding Guidelines

General Principles

• Follow existing patterns: Match the style of surrounding code
• Package functionality: Create well-defined library interfaces
• Use classes: Organize code into classes with clear responsibilities
• Add tests: Include unit tests for new functionality

Code Style

PowerToys follows specific style conventions:

• C++: Follow Microsoft style with 4-space indentation
• C#: Use .NET conventions with PascalCase for public members
• XAML: Use consistent spacing and naming

See the coding style guide for detailed rules.

Logging and Telemetry

• C++: Use spdlog for logging
• C#: Use the Logger class from Common.UI
• Telemetry: Use Telemetry:: namespace for metrics
• Log Levels: Use appropriate levels (Error, Warning, Info, Debug, Trace)

Best Practices

Write Clear Code

Use descriptive names and add comments for complex logic

Test Thoroughly

Include unit tests and manual validation for all changes

Keep PRs Focused

One logical change per PR makes review easier

Document Changes

Update docs when changing behavior or adding features

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

Our Standards

• Be respectful: Treat all contributors with respect
• Be collaborative: Work together to solve problems
• Be inclusive: Welcome newcomers and diverse perspectives
• Be professional: Keep discussions focused and constructive

Reporting Issues

If you experience or witness unacceptable behavior:

• Review the Code of Conduct FAQ
• Contact [e-mail]

Becoming a Collaborator

Active community contributors may be invited to join the PowerToys team as formal collaborators.

How to become a collaborator:

1. Make consistent, quality contributions
2. File helpful bug reports and suggestions
3. Review pull requests
4. Help other community members
5. Update documentation

When the time is right, Microsoft will reach out to you.

Resources

Developer Docs

Comprehensive developer documentation

GitHub Issues

Browse and file issues

Help Wanted

Find issues ready for contribution

Community

Meet the PowerToys community

Getting Help

If you need assistance:

• Questions: File an issue with your question
• Bug reports: Use the bug report template
• Feature requests: Use the feature request template
• General discussion: Join conversations in existing issues

Microsoft support is limited to the resources provided in this documentation and on GitHub. For support policy details, see SUPPORT.md.

Thank You

Thank you for contributing to PowerToys! Your efforts help make Windows more powerful and customizable for users around the world.