Welcome to the Windows UI Library (WinUI) repository. The WinUI repo is intended as a place for the WinUI team to gather community feedback, discuss issues with the community, and provide insight into bug fixes that the team is working on before updates are released. We welcome your input and contributions to all aspects of WinUI, including bug reports, doc updates, feature proposals, and API spec discussions.
This document contains general guidance. More specific guidance is included in the documents linked below and within the repository's Wiki pages.
Note this repository is not ready for open source collaboration at this time; this work is currently in progress. You can track the WinUI team's progress towards open source collaboration in the Phased Rollout to Open Source Collaboration discussion.
Note that all community interactions must abide by the Code of Conduct. We strive to be respectful & empathetic toward each other, and we extend this to our community as well. Our conduct guidelines help to ensure that discourse and feedback follows this same pattern of respect & empathy, and they also make it clear that non-constructive or hostile feedback is unacceptable. By following these guidelines, we can all enjoy the mutual respect that each WinUI team member, and each community member, deserve.
The WinUI documentation is a great resource for learning more about WinUI development. Within these docs, you can find information on how to create new WinUI applications, the full set of WinUI APIs and controls, and more.
You're welcome to propose changes to our documentation through the same link.
You can find usage examples of the controls available in WinUI in the WinUI 3 Gallery app. The source code for WinUI3 Gallery is available on GitHub at microsoft/WinUI-Gallery.
If you have a general question on how to use WinUI and are not sure it's a bug, ask in the Q&A discussion forum.
If you have an idea or feature request, post in the Ideas discussion forum.
If you have an issue which you think is a bug, please follow the Bug Report issue template and provide a stand-alone minimal repo project.
If you are reporting a security issue, please see the Security Policy.
For more information on how issues are handled from the community, see our contribution handling guidelines.
Please follow the New Feature or API Process before adding, removing, or changing public APIs or UI. Note: The WinUI team will only accept feature proposals for WinUI3.
All new public APIs, new UI, or breaking changes to existing features must go through that process before submitting code changes.
When experiencing a pain-point, it can be natural to focus on the negatives. However, telling the team what you'd like to prevent is less helpful and actionable than telling the team what you'd like to achieve.
Your feedback is most effective when it is a constructive call to action on the team, and is clear and detailed – especially on the "why" so that we can make sure whatever it is that we arrive at together appropriately focuses on your goal and your intended outcome from start to finish.
Examples of constructively phrased feedback:
Instead of:
- The state of the platform is disappointing. I am not going to consider WinUI until my trust has been earned.
Try this:
- Deprecation of past frameworks has left me burned. The following would go a long way in earning my trust because my company is trying to launch an app next year and will need it supported for at least 5 more:
- OSS
- High-confidence 5-year roadmap
- Guaranteed support timeline
This feedback provides clear actionable items that the WinUI team can take into consideration and address.
Here are some areas where your feedback can have a large impact:
It's very helpful to specify the "why" behind your request, even if it seems obvious. Comparisons can help, but shouldn't replace explanation.
- Ex: "I need
<feature>so that I can achieve<goal>. Otherwise, I have to<alternative>."
There are also usually great opportunities to have feature-related impact in our spec repo. Here, you can give direct feedback and help shape the new features and APIs that we're currently building.
We strive to be transparent about our product roadmap. Great examples of feedback to help us achieve this are:
- "I'd like to know the roadmap through
<timeframe>. Otherwise, I can't do<goal>. " - "The roadmap
<certain aspect - e.g., changes too much, not detailed enough, etc.>prevents me from being able to do<goal>. If you would instead<proposed alternative>, that would result in<clear benefit>."
It's helpful to be complete in explaining what another solution achieves for you and why it is important to you.
- Ex:"I'd like WinUI 3 to work with
<framework, language, library, technology, etc.>. Without this, I can't do<goal>."
There is often trade-off required when adjusting priorities - please be clear in comparing what is more important vs. less important to you, and the reason why.
- Ex: "I think
<specific area or feature set>should be prioritized before<other specific area or feature set>so that I can achieve<goal>. Without this, I have to<alternative>. "
Engagement includes feedback about learning materials and resources. It is always helpful to know where you prefer to be engaged and how you prefer to learn.
- "I would like to hear more about
<specific topic>in<resource>so that I can achieve<goal>." - "
<Resource>could be more inclusive and accessible if you considered<alternative>because<benefit>. Have you considered making these changes?"
Many of the resources we provide are also open source themselves! It can sometimes be more effective to leave feedback on the more specific repo. This includes:
Team process includes feedback about our repo and overall communication. Suggestions for improvement and proposed alternatives are very helpful here.
- Ex: "
<specific aspect of team process - e.g., response frequency, format>of the repo is making it hard for me to achieve<goal>. Please consider doing<alternative>instead because that would help<action>"
Note this repository is not ready for open source collaboration at this time; this work is currently in progress. You can track the WinUI team's progress towards open source collaboration in the Phased Rollout to Open Source Collaboration discussion.
WinUI will be taking a phased approach to opening up the repo:
| Phase | Description |
|---|---|
| Phase 1: Increased Mirror Frequency | After the WASDK 1.8 release (end of September), we'll begin more frequent mirroring of internal commits to GitHub to increase transparency and show progress. |
| Phase 2: 3rd Party Devs Build Locally | External developers will be able to clone and build the repo locally, with documentation to guide setup and dependencies. |
| Phase 3: 3rd Party Devs Contribute & Run Tests | Contributors will be able to submit PRs and run tests locally. We're working to untangle private dependencies and make test infrastructure publicly accessible. |
| Phase 4: GitHub as Center of Gravity | GitHub becomes the primary place for development, issue tracking, and community engagement. Internal mirrors will be phased out. |
Contributions from the community are greatly appreciated. We mark the most straightforward issues with labels. These issues are the best place to start if you are interested in contributing but are new to the codebase.
Another great way to help is by up-voting and commenting on feature proposals:
Content will be added to this section once the reposority is ready for open source contribution.
The WinUI team accepts code changes that improve WinUI or fix bugs, as long as they follow the processes outlined below and broadly align with our roadmap.
While we strive to accept all community contributions that meet the guidelines outlined here, please note that we may not merge changes that have narrowly-defined benefits due to compatibility risks and maintenance costs. We may also revert changes if they are found to be breaking.
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
The following rules must be followed for PRs that include files from another project:
- The license of the file is permissive.
- The license of the file is left intact.
- The contribution is correctly attributed in the 3rd party notices file in the repository, as needed.
Please format commit messages as follows (based on A Note About Git Commit Messages):
Summarize change in 50 characters or less
Provide more detail after the first line. Leave one blank line below the
summary and wrap all lines at 72 characters or less.
If the change fixes an issue, leave another blank line after the final
paragraph and indicate which issue is fixed in the specific format below.
Fix #42
Each pull request to main must pass checks within Azure DevOps. These pipelines build your change and run automated tests.
The license/CLA check confirms that you have completed the CLA.
Pull requests from a fork will not automatically trigger all of these checks. A member of the WinUI team can trigger the Azure Pipeline checks by commenting /azp run on the PR. The Azure Pipelines bot will then trigger the build.
In order to have PRs automatically merge once all checks have passed (including optional checks), maintainers can apply the auto merge label. It will take effect after an 8 hour delay.