diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c9aa069ef6..4577431086 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -3,4 +3,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. \ No newline at end of file +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb7a1c86fd..d06139d811 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,21 +14,21 @@ Contributions from the community in the form of feature requests and bugs are ha ## New contributors -We mark the most straightforward issues with labels. These issues are the place to start if you are interested in contributing but new to the codebase. +We mark the most straightforward issues with labels. These issues are the place to start if you are interested in contributing, but new to the codebase. -* [good first issues](https://github.com/Microsoft/microsoft-ui-xaml/labels/good%20first%20issue) -* [help wanted](https://github.com/Microsoft/microsoft-ui-xaml/labels/help%20wanted) +- [good first issues](https://github.com/Microsoft/microsoft-ui-xaml/labels/good%20first%20issue) +- [help wanted](https://github.com/Microsoft/microsoft-ui-xaml/labels/help%20wanted) Another great way to help is by voting and commenting on feature proposals: -* [feature request](https://github.com/Microsoft/microsoft-ui-xaml/labels/feature%20request) +- [feature request](https://github.com/Microsoft/microsoft-ui-xaml/labels/feature%20request) ## Code contribution guidelines ### Proposing new public APIs or UI -Please follow the [New Feature or API Process](docs/feature_proposal_process.md) before adding, removing, or changing public APIs or UI. -All new public APIs, new UI, or breaking changes to existing features **must** go through that process before submitting code changes. +Please follow the [New Feature or API Process](docs/feature_proposal_process.md) before adding, removing, or changing public APIs or UI. +All new public APIs, new UI, or breaking changes to existing features **must** go through that process before submitting code changes. You don't need to follow that process for bug fixes or other small changes. ### Contribution bar @@ -41,14 +41,14 @@ While we strive to accept all community contributions that meet the guidelines o For details see: -* [Setup and build environment](docs/developer_guide.md#Prerequisites) -* [Source code structure](docs/source_code_structure.md) -* [Contribution workflow](docs/contribution_workflow.md) -* [Coding style and conventions](docs/code_style_and_conventions.md) +- [Setup and build environment](docs/developer_guide.md#Prerequisites) +- [Source code structure](docs/source_code_structure.md) +- [Contribution workflow](docs/contribution_workflow.md) +- [Coding style and conventions](docs/code_style_and_conventions.md) ### Contributor License Agreement -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. +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 . 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. @@ -56,22 +56,19 @@ When you submit a pull request, a CLA-bot will automatically determine whether y The following rules must be followed for PRs that include files from another project: -* The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence). -* The license of the file is left intact. -* The contribution is correctly attributed in the [3rd party notices](https://github.com/dotnet/coreclr/blob/master/THIRD-PARTY-NOTICES.TXT) +- The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence). +- The license of the file is left intact. +- The contribution is correctly attributed in the [3rd party notices](https://github.com/dotnet/coreclr/blob/master/THIRD-PARTY-NOTICES.TXT) file in the repository, as needed. ## Documentation and usage samples -You can also read and contribute to the WinUI documentation here: -https://docs.microsoft.com/uwp/toolkits/winui +You can also read and contribute to the WinUI documentation here: [WinUI documentation](https://learn.microsoft.com/uwp/toolkits/winui) -You can find usage examples of the controls available in WinUI in the WinUI 3 Gallery app: - https://github.com/Microsoft/WinUI-Gallery/ +You can find usage examples of the controls available in WinUI in the WinUI 3 Gallery app: [WinUI 3 Gallery app](https://github.com/Microsoft/WinUI-Gallery/) - Which can also be installed from the Microsoft Store: - https://apps.microsoft.com/detail/9p3jfpwwdzrc - - ## API spec discussions +Which can also be installed from the Microsoft Store: [Microsoft Store](https://apps.microsoft.com/detail/9p3jfpwwdzrc) -Before new features are added to WinUI, we always perform a thorough API review and spec discussion. This can range from a single new API to an entire new control featuring dozens of new APIs. Joining such a spec discussion is a great opportunity for developers to help ensuring that new WinUI APIs will look and feel natural. In addition, spec discussions are the follow-up to feature proposals and will go into much finer details than the initial proposal. As such, taking part in these discussions gives developers the chance to be involved in the complete development process of new WinUI features - from their initial high-level inception right down to specific implementation/behavior details. These discussions take place in the WInUI repository, i.e. this repository. +## API spec discussions + +Before new features are added to WinUI, we always perform a thorough API review and spec discussion. This can range from a single new API to an entire new control featuring dozens of new APIs. Joining such a spec discussion is a great opportunity for developers to help ensuring that new WinUI APIs will look and feel natural. In addition, spec discussions are the follow-up to feature proposals and will go into much finer details than the initial proposal. As such, taking part in these discussions gives developers the chance to be involved in the complete development process of new WinUI features - from their initial high-level inception right down to specific implementation/behavior details. These discussions take place in the WinUI repository, i.e. this repository. diff --git a/CONTRIBUTING_feedback_and_requests.md b/CONTRIBUTING_feedback_and_requests.md index 2c0dc3c7e7..717e6c6770 100644 --- a/CONTRIBUTING_feedback_and_requests.md +++ b/CONTRIBUTING_feedback_and_requests.md @@ -6,62 +6,66 @@ The guide below outlines how you can formulate this feedback for maximum effect ## Phrasing constructively -When experiencing a pain-point, it can be natural to focus on the negatives and resolving things from the perspective of the negative. 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*. +When experiencing a pain-point, it can be natural to focus on the negatives and resolving things from the perspective of the negative. 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. +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:** +### 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. +- 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. - - + +- 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. + ## Sample areas where your feedback can have large impact -- ### Features - - 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`>`." +### Features + +- It's very helpful to specify the "why" behind your request, even if it seems obvious. Comparisons can help, but shouldn't replace explanation. +- Example: "I need \ so that I can achieve \. Otherwise, I have to \." + + There are also usually great opportunities to have feature-related impact in our [spec repo](https://github.com/microsoft/microsoft-ui-xaml-specs/tree/master). Here, you can give direct feedback and help shape the new features and APIs that we're currently building. - There are also usually great opportunities to have feature-related impact in our [spec repo](https://github.com/microsoft/microsoft-ui-xaml-specs/tree/master). Here, you can give direct feedback and help shape the new features and APIs that we're currently building. +### Future/Roadmap -- ### Future/Roadmap - - We strive to be transparent about our [product roadmap](https://aka.ms/winui3/feature-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`>`." +- We strive to be transparent about our [product roadmap](https://aka.ms/winui3/feature-roadmap). Great examples of feedback to help us achieve this are: + - "I'd like to know the roadmap through \. Otherwise, I can't do \." + - "The roadmap \ prevents me from being able to do \. If you would instead \, that would result in \." -- ### Ecosystem - - 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`>`." +### Ecosystem -- ### Prioritization within WinUI - - 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`>`. " +- It's helpful to be complete in explaining what another solution achieves for you and why it is important to you. + - Example:"I'd like WinUI 3 to work with \. Without this, I can't do \." + +### Prioritization within WinUI + +- 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. + - Example: "I think \ should be prioritized before \ so that I can achieve \. Without this, I have to \. " + +### Engagement + +- 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 \ in \ so that I can achieve \." + - "\ could be more inclusive and accessible if you considered \ because \. Have you considered making these changes?" -- ### Engagement - - 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: - - [documentation](https://github.com/MicrosoftDocs/windows-uwp) - - [website (`gh-pages` branch of this repo)](https://github.com/microsoft/microsoft-ui-xaml/tree/gh-pages) - - [Xaml Controls Gallery (sample app)](https://github.com/microsoft/Xaml-Controls-Gallery/tree/master) - -- ### Team Process - - 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`>`" +- [documentation](https://github.com/MicrosoftDocs/windows-uwp) +- [website (gh-pages branch of this repo)](https://github.com/microsoft/microsoft-ui-xaml/tree/gh-pages) +- [XAML Controls Gallery (sample app)](https://github.com/microsoft/Xaml-Controls-Gallery/tree/master) + +### Team Process +- Team process includes feedback about our repo and overall communication. Suggestions for improvement and proposed alternatives are very helpful here. + - Example: "\ of the repo is making it hard for me to achieve \. Please consider doing \ instead because that would help \." ## Mutual respect @@ -69,4 +73,4 @@ We strive to be respectful & empathetic toward each other, and we extend this to 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. -Refer to our [conduct guidelines](https://github.com/microsoft/microsoft-ui-xaml/blob/main/CODE_OF_CONDUCT.md) for more guidance here. +Refer to our [conduct guidelines](https://github.com/microsoft/microsoft-ui-xaml/blob/main/CODE_OF_CONDUCT.md) for more guidance here. diff --git a/README.md b/README.md index 49ebbc30d1..e90d140c18 100644 --- a/README.md +++ b/README.md @@ -31,22 +31,22 @@ WinUI is a user interface layer that contains modern controls and styles for bui ## 📋 Getting started with WinUI -For WinUI, your app's users must be on Windows 10 1809 - Build 17763 or newer (including Windows Insider Previews). +For WinUI, your app's users must be on Windows 10 1809 - build 17763 or newer (including Windows Insider Previews). The full documentation of WinUI can be found on [Microsoft Learn](https://learn.microsoft.com/windows/apps/): + - [Get started with WinUI](https://learn.microsoft.com/windows/apps/get-started/start-here) - [Build your first WinUI app](https://learn.microsoft.com/windows/apps/tutorials/winui-notes/) - [Migrate from UWP to the Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw) - [Windows Runtime APIs not supported in desktop apps](https://learn.microsoft.com/windows/apps/desktop/modernize/desktop-to-uwp-supported-api) - [WinUI & Windows App SDK samples](https://learn.microsoft.com/windows/apps/get-started/samples) -
- ## 🖼️ WinUI 3 Gallery + Make sure to also check out the [WinUI 3 Gallery](https://aka.ms/winui-gallery), our interactive sample experience showing everything you can do with WinUI.

-WinUI 3 Gallery + WinUI 3 Gallery

@@ -57,6 +57,7 @@ Make sure to also check out the [WinUI 3 Gallery](https://aka.ms/winui-gallery),

## 📺 WinUI Community Call + The WinUI Community Call is your opportunity to learn about WinUI and to engage with the WinUI team and community. Join us online on YouTube at the [Windows Developer channel](https://www.youtube.com/playlist?list=PLI_J2v67C23ZqsolUDaHoFkF1GKvGrttB). ## 📢 Contributing to WinUI @@ -73,16 +74,17 @@ For information on how to contribute, please see [Contributing to WinUI](CONTRIB > [WinUI OSS Update post](https://github.com/microsoft/microsoft-ui-xaml/discussions/10700) to check the > latest status. > -> For the latest code and updates, use the [`winui3/main`](https://github.com/microsoft/microsoft-ui-xaml/tree/winui3/main) branch. +> For the latest code and updates, use the [winui3/main](https://github.com/microsoft/microsoft-ui-xaml/tree/winui3/main) branch. ## 🛣️ Roadmap -For info on the WinUI release schedule and high level plans please see the [WinUI roadmap](https://aka.ms/winappsdk/plans). +For info about the WinUI release schedule and high level plans please see the [WinUI roadmap](https://aka.ms/winappsdk/plans). ## 🔧 WinUI for UWP -WinUI for UWP (WinUI 2) is a library of controls that provides Microsoft UI controls and features for [UWP apps](https://docs.microsoft.com/windows/uwp/index). Learn more about WinUI for UWP [here](https://aka.ms/winui2) or download the source code [here](https://github.com/microsoft/microsoft-ui-xaml/tree/winui2/main). -You can get the WinUI 2 Gallery [on the Microsoft Store](https://www.microsoft.com/store/productId/9MSVH128X2ZT?ocid=pdpshare) and see the source code [here](https://github.com/microsoft/WinUI-Gallery/tree/winui2). +WinUI for UWP (WinUI 2) is a library of controls that provides Microsoft UI controls and features for [UWP apps](https://learn.microsoft.com/windows/uwp/index). Learn more about WinUI for UWP [on MS Learn](https://aka.ms/winui2) or download the source code [on GitHub](https://github.com/microsoft/microsoft-ui-xaml/tree/winui2/main). + +You can get the WinUI 2 Gallery [in the Microsoft Store](https://www.microsoft.com/store/productId/9MSVH128X2ZT?ocid=pdpshare) and see the source code [on GitHub](https://github.com/microsoft/WinUI-Gallery/tree/winui2). ### Data/Telemetry diff --git a/SECURITY.md b/SECURITY.md index f7b89984f0..f0b94a3574 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,10 +1,10 @@ -## Security +# Security Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://learn.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. ## Reporting Security Issues @@ -12,19 +12,19 @@ If you believe you have found a security vulnerability in any Microsoft-owned re Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). -If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/msrc/pgp-key-msrc). -You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: - * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. @@ -36,6 +36,6 @@ We prefer all communications to be in English. ## Policy -Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/msrc/cvd). \ No newline at end of file diff --git a/docs/contribution_handling.md b/docs/contribution_handling.md index e639e31851..f081ef366e 100644 --- a/docs/contribution_handling.md +++ b/docs/contribution_handling.md @@ -16,8 +16,8 @@ Please file questions and discussions as discussions, not issues. Feature proposals for WinUI 3 are categorized based on the likely timeframe in which the feature team can consider them. -1. Short-term, less than a year -2. Long-term, not likely in the next year +1. Short-term, less than a year +2. Long-term, not likely in the next year All feature proposals are automatically categorized as long-term and unlikely to be considered, although the WinUI team might change the priority based on customer and business needs. If the WinUI team does close a feature proposal, we will indicate the reason why and how it fits into our plans. Closing a proposal does not mean that the team will never consider it. We encourage the community to add comments or interact with a proposal at any time, even a closed one, to signal its importance to the team. @@ -52,4 +52,4 @@ WinUI 3 bugs are triaged and prioritized based on how much the bug impacts one o Bugs filed in relation to preview and experimental releases are triaged with the same criteria as stable releases and are intended to assist in identifying and fixing those bugs before they make their way to a stable release. -Bugs filed on GitHub will be automatically mirrored to our internal bug tracking system and updates to them are automatically mirrored back to GitHub with appropriate tags. This way, the bugs we're working on and their progress are transparent. The only information we will reflect from our system externally is the state and release of the bug, not all the fine details; if a bug is resolved or closed, that's reflected on GitHub, and as bugs are worked on, the release for that fix will be reflected with a milestone on GitHub. \ No newline at end of file +Bugs filed on GitHub will be automatically mirrored to our internal bug tracking system and updates to them are automatically mirrored back to GitHub with appropriate tags. This way, the bugs we're working on and their progress are transparent. The only information we will reflect from our system externally is the state and release of the bug, not all the fine details; if a bug is resolved or closed, that's reflected on GitHub, and as bugs are worked on, the release for that fix will be reflected with a milestone on GitHub. diff --git a/docs/contribution_workflow.md b/docs/contribution_workflow.md index bf770734f1..34fde83a9f 100644 --- a/docs/contribution_workflow.md +++ b/docs/contribution_workflow.md @@ -1,113 +1,113 @@ # Contribution Workflow -You can contribute to WinUI with issues and PRs. Simply filing issues for -problems you encounter is a great way to contribute. Contributing -implementations is greatly appreciated. +You can contribute to WinUI with issues and Pull Requests. Simply filing issues for problems you encounter is a great way to contribute. +Contributing implementations is greatly appreciated. -Good issues to work on are issues tagged with -[help wanted](https://github.com/microsoft/microsoft-ui-xaml/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or +Good issues to work on are issues tagged with +[help wanted](https://github.com/microsoft/microsoft-ui-xaml/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [good first issue](https://github.com/microsoft/microsoft-ui-xaml/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). ## Suggested Workflow We use and recommend the following workflow: -1. Create an issue for your work. - * You can skip this step for trivial changes. - * Reuse an existing issue on the topic, if there is one. - * If your change adds or changes public API or UI, first follow + +1. Create an issue for your work. + - You can skip this step for trivial changes. + - Reuse an existing issue on the topic, if there is one. + - If your change adds or changes public API or UI, first follow the [New Feature or API Process](feature_proposal_process.md). - * Clearly state that you are going to take on implementing it, if that's - the case. You can request that the issue be assigned to you. Note: The + - Clearly state that you are going to take on implementing it, if that's + the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person. -2. Create a personal fork of the repository on GitHub (if you don't already +2. Create a personal fork of the repository on GitHub (if you don't already have one). -3. Create a branch off of main (`git checkout -b mybranch`). - * Name the branch so that it clearly communicates your intentions. - * Branches are useful since they isolate your changes from incoming changes - from upstream. They also enable you to create multiple PRs from the same +3. Create a branch off of main (`git checkout -b mybranch`). + - Name the branch so that it clearly communicates your intentions. + - Branches are useful since they isolate your changes from incoming changes + from upstream. They also enable you to create multiple PRs from the same fork. -4. Make and commit your changes. - * Please follow our [Commit Messages](#Commit-Messages) +4. Make and commit your changes. + - Please follow our [Commit Messages](#commit-messages) guidance. 5. Add new tests corresponding to your change, if applicable. -6. Build the repository with your changes. - * Make sure that the builds are clean. - * Make sure that the tests are all passing, including your new tests. -7. Create a pull request (PR) against the upstream repository's main branch. - * Push your changes to your fork on GitHub (if you haven't already). - - Note: It is okay for your PR to include a large number of commits. Once - your change is accepted, you will be asked to squash your commits into one +6. Build the repository with your changes. + - Make sure that the builds are clean. + - Make sure that the tests are all passing, including your new tests. +7. Create a pull request (PR) against the upstream repository's main branch. + - Push your changes to your fork on GitHub (if you haven't already). + - Note: It is okay for your PR to include a large number of commits. Once + your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged. - - Note: It is okay to create your PR as "[WIP]" on the upstream repo before - the implementation is done. This can be useful if you'd like to start the - feedback process while you're still working on the implementation. State + - Note: It is okay to create your PR as "[WIP]" on the upstream repo before + the implementation is done. This can be useful if you'd like to start the + feedback process while you're still working on the implementation. State that this is the case in the initial PR comment. ## DOs and DON'Ts Please do: -* **DO** follow existing coding style. -* **DO** give priority to the current style of the project or file you're + +- **DO** follow existing coding style. +- **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines. -* **DO** include tests when adding new features. When fixing bugs, start with +- **DO** include tests when adding new features. When fixing bugs, start with adding a test that highlights how the current behavior is broken. -* **DO** keep the discussions focused. When a new or related topic comes up +- **DO** keep the discussions focused. When a new or related topic comes up it's often better to create new issue than to side track the discussion. -* **DO** blog and tweet (or whatever) about your contributions, frequently! +- **DO** blog and tweet (or whatever) about your contributions, frequently! Please do not: -* **DON'T** make PRs for style changes. -* **DON'T** surprise us with big pull requests. Instead, file an issue and -start a discussion so we can agree on a direction before you invest a large + +- **DON'T** make PRs for style changes. +- **DON'T** surprise us with big pull requests. Instead, file an issue and +start a discussion so we can agree on a direction before you invest a large amount of time. -* **DON'T** commit code that you didn't write (attesting this is part of the -[CLA](https://cla.microsoft.com)). If you find code that you think is a good +- **DON'T** commit code that you didn't write (attesting this is part of the +[CLA](https://cla.microsoft.com)). If you find code that you think is a good fit to add to WinUI, file an issue and start a discussion before proceeding. -* **DON'T** submit PRs that alter licensing related files or headers. If you -believe there's a problem with them, file an issue and we'll be happy to +- **DON'T** submit PRs that alter licensing related files or headers. If you +believe there's a problem with them, file an issue and we'll be happy to discuss it. -* **DON'T** add or change public API or UI without filing an issue and +- **DON'T** add or change public API or UI without filing an issue and discussing it first: see the [New Feature or API Process](feature_proposal_process.md). ## Checks Each pull request to `main` must pass the following checks: -###### [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) +- [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) This pipeline builds your change and runs automated tests. These tests should match what you're able to run with local automated testing using Test Explorer. It also creates a NuGet package to match your change. -###### license/cla +- license/cla This check confirms that you have completed the [CLA](https://cla.microsoft.com). - -Pull requests from a fork will not automatically trigger all of these checks. A member of the WinUI +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](https://github.com/Microsoft/microsoft-ui-xaml/labels/auto%20merge) +In order to have PRs automatically merge once all checks have passed (including optional +checks), maintainers can apply the [auto merge](https://github.com/Microsoft/microsoft-ui-xaml/labels/auto%20merge) label. It will take effect after an 8 hour delay. ### Other Pipelines -Unlike the above checks these are not required for all PRs, but you may see them on some PRs so we +Unlike the above checks these are not required for all PRs, but you may see them on some PRs so we define them here: -#### [WinUI-Public-MUX-CI](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=20) +- [WinUI-Public-MUX-CI](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=20) -This pipeline extends [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) -to validate more platforms, adding Debug and ARM. It is run after your changes are merged to -main. +This pipeline extends [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) +to validate more platforms, adding Debug and ARM. It is run after your changes are merged to main. ## Commit Messages Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)): -``` +```text Summarize change in 50 characters or less Provide more detail after the first line. Leave one blank line below the @@ -117,4 +117,4 @@ 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 -``` \ No newline at end of file +``` diff --git a/docs/debugging_buildfailures.md b/docs/debugging_buildfailures.md index 65d1c0e7b2..3bd4940136 100644 --- a/docs/debugging_buildfailures.md +++ b/docs/debugging_buildfailures.md @@ -1,19 +1,20 @@ # Capturing binlogs + Capturing and providing binlog files can help with debugging build and packaging issues. In order to collect binlogs, please follow these steps: Generally, it is encouraged to collect binlog files through the CLI of MSBuild as they tend to be easier to diagnose, but both methods of creating binlog files are fine. ## Collecting binlogs through Visual Studio -1. Download the VS Project System Tools extension: [For VS 2019](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools) | [For VS 2022](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools2022) -3. Set the **Build Log File** verbosity to `Diagnostics`: `Tools->Options->Projects and Solutions->MSBuild project build log file verbosity`:
-![Screenshot of Build and run options](./images/binlog-images/buildandrunoptions.png) - -3. Go to View->Other Windows->Build Logging:
-![Screenshot of Build Logging menu item](./images/binlog-images/buildlogging_menuitem.png) -4. To start taking logs, press the play button:
+1. Download the VS **Project System Tools** extension: + - [For VS 2019](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools) + - [For VS 2022](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools2022) +2. Set the **Build Log File** verbosity to `Diagnostics`: **Tools** > **Options** > **Projects and Solutions** > **MSBuild project build log file verbosity**: + ![Screenshot of Build and run options](./images/binlog-images/buildandrunoptions.png) +3. Go to **View** > **Other Windows** > **Build Logging**: + ![Screenshot of Build Logging menu item](./images/binlog-images/buildlogging_menuitem.png) +4. To start taking logs, press the play button: ![Screenshot of Build Logging window](./images/binlog-images/buildlogging_window.png) - 5. Run the steps that resulted in errors, e.g. building your project. The steps that failed show up as "Failed". Those files have the file extension ".binlog" and can be shared to help debugging build and packaging issues. ## Collection binlogs through the command line @@ -22,10 +23,14 @@ To collect binlogs through the command line interface of MSBuild using the Visua For example, to build your solution in x86 release and collect binlogs, you can use the following: -`msbuild /p:Platform=x86 /p:Configuration=Release /bl` +```cli +msbuild /p:Platform=x86 /p:Configuration=Release /bl +``` If you encounter issues while creating app packages, you can use the following command to simulate collect binlogs: -`msbuild /p:AppxBundlePlatforms=x86 /p:Platform=x86 /p:Configuration=Release /p:BuildAppxUploadPackageForUap=true /bl` +```cli +msbuild /p:AppxBundlePlatforms=x86 /p:Platform=x86 /p:Configuration=Release /p:BuildAppxUploadPackageForUap=true /bl +``` In case of investigating build failures with the WinUI source code, please run the `devcmd.cmd` script at the root of the repository first. diff --git a/docs/debugging_crashes.md b/docs/debugging_crashes.md index 311d58859d..f3225b473e 100644 --- a/docs/debugging_crashes.md +++ b/docs/debugging_crashes.md @@ -1,6 +1,7 @@ # Debugging Crashes This document covers the following topics: + 1. [How to get a crash dump](debugging_crashes.md#How-to-get-a-crash-dump) 2. [How to get a good callstack for crashes](debugging_crashes.md#How-to-get-a-good-callstack-for-crashes) @@ -9,6 +10,7 @@ This document covers the following topics: ### Using Visual Studio If the crash is in your app which you can launch from Visual Studio, or if you can attach to the app with Visual Studio prior to the crash, then you can use these steps: + 1. If launching the app from Visual Studio, set Visual Studio to debug either as "Native Only" or as "Mixed (Managed and Native)" before launching the app. If attaching to a running app, in the "Attach to Process" dialog be sure to change the "Attach to:" settings to include "Native" if it isn't shown for the process, and then attach. 2. Run the repro. @@ -19,23 +21,25 @@ This type of crash might manifest as a crash in your app, usually with a functio ### Using WinDbg -In [WinDbg](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools), use `.dump /ma ` to save a full memory dump to the specified file when the crash happens. -* If the crash happens sometime after app launch, then you can launch the app, attach to the app with WinDbg, and then do the repro steps to hit the crash. -* If the crash happens on launch, then [WinDbg Preview](https://www.microsoft.com/store/p/windbg/9pgjgd53tn86) is recommended, since it contains a "Launch app package" option in -"Start Debugging" which can launch and debug UWP and packaged apps from launch. +In [WinDbg](https://learn.microsoft.com/windows-hardware/drivers/debugger/debugger-download-tools), use `.dump /ma ` to save a full memory dump to the specified file when the crash happens. + +- If the crash happens sometime after app launch, then you can launch the app, attach to the app with WinDbg, and then do the repro steps to hit the crash. +- If the crash happens on launch, then [WinDbg Preview](https://www.microsoft.com/store/p/windbg/9pgjgd53tn86) is recommended, since it contains a "Launch app package" option in "Start Debugging" which can launch and debug UWP and packaged apps from launch. ### Other options -Another option is to set some regkeys to tell Windows to keep some crash dumps locally (see https://docs.microsoft.com/en-us/windows/win32/wer/collecting-user-mode-dumps). -For example, running these commands in an administrative command prompt will set regkeys to tell Windows to save full (type=2) dumps into `C:\dumps`: +Another option is to set some regkeys to tell Windows to keep some crash dumps locally (see [Collecting User-Mode Dumps](https://learn.microsoft.com/windows/win32/wer/collecting-user-mode-dumps)). For example, running these commands in an administrative command prompt will set regkeys to tell Windows to save full (type=2) dumps into `C:\dumps`: +```cmd reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /v DumpFolder /d "C:\dumps" reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps" /v DumpType /t REG_DWORD /d 2 +``` -After you repro the crash, you should find a dump in the specified folder. +After you reproduce the crash, you should find a dump in the specified folder. You can automate crash dump collection and filing bugs by following these steps: -1. Download the script at https://aka.ms/RNW/analyze-crash.ps1, for example to `C:\temp` + +1. Download the script at [analyze-crash.ps1](https://aka.ms/RNW/analyze-crash.ps1), for example to `C:\temp` 2. Open an admin PowerShell. If you haven't enabled running unsigned scripts yet, do that by running: `Set-ExecutionPolicy Unrestricted` 3. Run the script and pass it the name of your app's exe: `C:\temp\analyze-crash.ps1 -ExeName MyApp -Repo microsoft/microsoft-ui-xaml` The script will set up automatic crash dump collection for your app, download the native debugging tools (including the command-line debugger cdb), and ask you to reproduce the crash. @@ -53,12 +57,12 @@ But if it is a stowed exception crash, which has exception code: 0xc000027b, the Stowed exception crashes save away a possible error, which gets used later if no one handles the exception. XAML sometimes decides the error is fatal immediately, in which case the direct crash stack may be good, but more frequently the stack has unwound before it was determined to be fatal. -This channel9 talk describes stowed exceptions in more detail: https://channel9.msdn.com/Shows/Inside/C000027B?term=stowed%20exception&lang-en=true. +This channel9 talk describes stowed exceptions in more detail: [Channel 9 talk on stowed exceptions](https://channel9.msdn.com/Shows/Inside/C000027B?term=stowed%20exception&lang-en=true). For stowed exception crashes, you can get more info on the crash by loading a crash dump in WinDbg and then using !pde.dse to dump the stowed exceptions. -The !pde debugger extension is available [here](https://onedrive.live.com/?authkey=%21AJeSzeiu8SQ7T4w&id=DAE128BD454CF957%217152&cid=DAE128BD454CF957) in the PDE*.zip. +The !pde debugger extension is available [PDE debugger extension download](https://onedrive.live.com/?authkey=%21AJeSzeiu8SQ7T4w&id=DAE128BD454CF957%217152&cid=DAE128BD454CF957) in the PDE*.zip. (It is linked off the channel9 page above.) -Put the appropiate x64 or x86 dll in that zip in the winext directory of a WinDbg install, and then "!pde.dse" should work on stowed exception crash dumps. +Put the appropriate x64 or x86 dll in that zip in the winext directory of a WinDbg install, and then "!pde.dse" should work on stowed exception crash dumps. Frequently there will be multiple stowed exceptions, with some at the end which got handled/ignored. Most commonly, the first stowed exception is the interesting one. diff --git a/docs/feature_proposal_process.md b/docs/feature_proposal_process.md index 4cb972c3ee..85bddc3700 100644 --- a/docs/feature_proposal_process.md +++ b/docs/feature_proposal_process.md @@ -1,20 +1,20 @@ -# New Feature or API Process +# New feature or API process -We welcome community contributions and input to the WinUI Library, including feature ideas and code contributions. +We welcome community contributions and input to the WinUI Library, including feature ideas and code contributions. -This document outlines the process for how you can propose or contribute new features. +This document outlines the process to propose or contribute new features. -### You need to follow this process for: +You need to follow this process for: -* Code changes that add, remove, or alter public API -* Features that add or alter the user experience (e.g. new visual designs) -* Changing any core functionality documented on docs.microsoft.com +- Code changes that add, remove, or alter public API +- Features that add or alter the user experience (e.g. new visual designs) +- Changing any core functionality documented on learn.microsoft.com -### You don't need to follow this process for: +You don't need to follow this process for: -* Fixing bugs -* Submitting PRs that don't alter major functionality or public API -(e.g. internal performance improvements) +- Fixing bugs +- Submitting PRs that don't alter major functionality or public API +(e.g. internal performance improvements) ## Process summary @@ -24,37 +24,37 @@ This document outlines the process for how you can propose or contribute new fea 0. Please search the [issue tracker](https://github.com/microsoft/microsoft-ui-xaml/issues) for a similar idea first: there may already be an issue you can contribute to. -1. **Create Issue** -All code changes must be tied to an Issue. -To propose a new feature or API please start by filing a new issue in the [issue tracker](https://github.com/microsoft/microsoft-ui-xaml/issues) using the [Feature Proposal template](https://github.com/Microsoft/microsoft-ui-xaml/issues/new?template=feature_proposal.md). +1. **Create Issue** +All code changes must be tied to an issue. +To propose a new feature or API, please start by filing a new issue in the [issue tracker](https://github.com/microsoft/microsoft-ui-xaml/issues) using the [Feature Proposal template](https://github.com/Microsoft/microsoft-ui-xaml/issues/new?template=feature_proposal.md). Include as much detail as you have. It's fine if it's not a complete design: just a summary and rationale is a good starting point. -2. **Wait for Team Owner** +2. **Wait for Team Owner** We will assign a WinUI team owner to your issue. The WinUI team regularly triages all incoming issues. -3. **Discussion** +3. **Discussion** We'll keep the issue open for community discussion until the team owner decides it's ready or should be closed. Note that if an issue isn't a high priority or has many open questions then it might stay open for a long time. -4. **Owner Review** +4. **Owner Review** The WinUI team will review the proposal and either approve or close the issue based on whether it broadly aligns with the [WinUI roadmap](roadmap.md) and [contribution guidelines](../CONTRIBUTING.md). -5. **API Review** +5. **API Review** If the feature adds new APIs then we'll start an API review in the [WinUI API review repo](https://github.com/microsoft/microsoft-ui-xaml-specs). All new public APIs must be reviewed before merging. -6. **Implementation** +6. **Implementation** A feature can be implemented by you, the WinUI team, or other community members. -Code contributions are greatly appreciated: feel free to work on any reviewed feature you proposed, or choose one in the backlog and send us a PR. Please let us know in the issue comments if you are actively working on implementing a feature so we can ensure it's assigned to you. -Our contribution guidelines can be found [here](../CONTRIBUTING.md). +Code contributions are greatly appreciated: feel free to work on any reviewed feature you proposed, or choose one in the backlog and send us a PR. Please let us know in the issue comments if you are actively working on implementing a feature so we can ensure it's assigned to you. +Our contribution guidelines can be found [in this file](../CONTRIBUTING.md). -7. **Merge** +7. **Merge** Once a feature is complete and tested according to the [contribution guidelines](../CONTRIBUTING.md) you can send us a PR to merge it to main. -8. **Documentation and sample updates** -We will update the [documentation on docs.microsoft.com](https://docs.microsoft.com/windows/uwp) and if applicable add a sample to the [Xaml Controls Gallery](https://github.com/Microsoft/Xaml-Controls-Gallery) app. +8. **Documentation and sample updates** +We will update the [documentation on learn.microsoft.com](https://learn.microsoft.com/windows/uwp) and if applicable add a sample to the [WinUI 3 Gallery](https://github.com/microsoft/WinUI-Gallery) app. Feel free to also contribute to docs and samples! Once the docs and samples are updated we'll close the issue. -9. **Binaries** -We periodically produce signed prerelease binaries from the main branch which are published to [NuGet](https://www.nuget.org/profiles/winui): see the [Roadmap](roadmap.md) for info on build frequency. +9. **Binaries** +We periodically produce signed prerelease binaries from the main branch which are published to [NuGet](https://www.nuget.org/profiles/winui): see the [Roadmap](roadmap.md) for info on build frequency. After the feature has been sufficiently validated as part of a prerelease package we will include it in the next stable binary release on NuGet. diff --git a/docs/triage.md b/docs/triage.md index c172b88271..f79de10c1b 100644 --- a/docs/triage.md +++ b/docs/triage.md @@ -9,7 +9,7 @@ For more info about our strategy for triaging bugs, see how we [handle contribut ### Triage labels -1. New and re-opened issues are marked with `needs-triage`. +1. New and re-opened issues are marked with the `needs-triage` label. 2. Issues with `needs-assignee-attention` should be investigated by the assignee as top priority. 3. Issues with `needs-author-feedback` are waiting for the author to reply. @@ -18,12 +18,13 @@ Because many groups are involved in WinUI we have `team-...` labels to help filt ### Triage process For each issue with `needs-triage`: -* Feature proposals: + +- Feature proposals: - Triage makes first pass to ask clarifying questions. If it's ok then: - - Spec owner gets assigned - - Gets added to `New proposal` in feature tracking board - - Assigned owner is responsible for following the feature process -* Everything else: + - Spec owner gets assigned + - Gets added to `New proposal` in feature tracking board + - Assigned owner is responsible for following the feature process +- Everything else: - If author needs to provide more info, ask in comments and add `needs-author-feedback` - Add a team label (`team-Controls`, `team-Framework`, etc) if missing - Add area tag(s) @@ -32,36 +33,37 @@ For each issue with `needs-triage`: - Consider adding `help wanted` or `good first issue` to encourage community engagement - Add `nice to have` for low priority issues -The temporary `needs-assignee-attention` label is intended for issues which need additional investigation, like debugging or another teams input, to determine how to route them. +The temporary `needs-assignee-attention` label is intended for issues which need additional investigation, like debugging or another teams input, to determine how to route them. ### Backlog -[Assigned issues](https://github.com/microsoft/microsoft-ui-xaml/issues/assigned/*) are being investigated or worked on. This doesn't mean they *will* be fixed soon, just that they are on the short list for that person to investigate, and possibly fix. They may get unassigned. +[Assigned issues](https://github.com/microsoft/microsoft-ui-xaml/issues/assigned/*) are being investigated or worked on. This doesn't mean they _will_ be fixed soon, just that they are on the short list for that person to investigate, and possibly fix. They may get unassigned. + +[Unassigned issues](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+no%3Aassignee) are the backlog. -[Unassigned issues](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+no%3Aassignee) are the backlog. - ### Triage queries Shortcuts to triage queries for the team. Note that these include closed issues because external comments on closed issues may not be noticed, so we have a bot rule that adds `needs-triage` to closed issues too. -* [Controls Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Aneeds-triage+-label%3Ateam-framework+-label%3Ateam-reach+-label%3Ateam-rendering+-label%3Ateam-ink+-label%3Ateam-compinput++-label%3Ateam-markup+) -* [Framework Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Framework+label%3Aneeds-triage+) -* [Markup Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Markup+label%3Aneeds-triage+) -* [Reach Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Reach+label%3Aneeds-triage+) -* [Rendering Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Rendering+label%3Aneeds-triage+) +- [Controls Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Aneeds-triage+-label%3Ateam-framework+-label%3Ateam-reach+-label%3Ateam-rendering+-label%3Ateam-ink+-label%3Ateam-compinput++-label%3Ateam-markup+) +- [Framework Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Framework+label%3Aneeds-triage+) +- [Markup Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Markup+label%3Aneeds-triage+) +- [Reach Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Reach+label%3Aneeds-triage+) +- [Rendering Triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Ateam-Rendering+label%3Aneeds-triage+) -* [Root node triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Aneeds-triage+-label%3Ateam-controls+-label%3Ateam-framework+-label%3Ateam-reach+-label%3Ateam-rendering+-label%3Ateam-ink+-label%3Ateam-compinput++-label%3Ateam-markup+) -- issues not assigned to a team yet. +- [Root node triage](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=label%3Aneeds-triage+-label%3Ateam-controls+-label%3Ateam-framework+-label%3Ateam-reach+-label%3Ateam-rendering+-label%3Ateam-ink+-label%3Ateam-compinput++-label%3Ateam-markup+) -- issues not assigned to a team yet. We also need to monitor: -* [needs-assignee-attention](https://github.com/microsoft/microsoft-ui-xaml/labels/needs-assignee-attention) -* [needs-author-feedback](https://github.com/microsoft/microsoft-ui-xaml/labels/needs-author-feedback) + +- [needs-assignee-attention](https://github.com/microsoft/microsoft-ui-xaml/labels/needs-assignee-attention) +- [needs-author-feedback](https://github.com/microsoft/microsoft-ui-xaml/labels/needs-author-feedback) ### Other useful links for contributors -* [good first issue](https://github.com/microsoft/microsoft-ui-xaml/labels/good%20first%20issue) -* [help wanted](https://github.com/microsoft/microsoft-ui-xaml/labels/help%20wanted) -* [unassigned bugs in WinUI 2.x](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Ateam-Controls+no%3Aassignee+-label%3A%22feature+proposal%22++-label%3Aneeds-winui-3+label%3Abug+-label%3Awinui3%CE%B1) +- [good first issue](https://github.com/microsoft/microsoft-ui-xaml/labels/good%20first%20issue) +- [help wanted](https://github.com/microsoft/microsoft-ui-xaml/labels/help%20wanted) +- [unassigned bugs in WinUI 2.x](https://github.com/microsoft/microsoft-ui-xaml/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Ateam-Controls+no%3Aassignee+-label%3A%22feature+proposal%22++-label%3Aneeds-winui-3+label%3Abug+-label%3Awinui3%CE%B1) ## Bot rules @@ -76,4 +78,3 @@ We also need to monitor: 1. Remove `needs-triage` label when an issue is closed. 1. Remove `needs-triage` when a closed issue has a reply by someone with write access to the repo. 1. Replace `needs-author-feedback` label with `needs-assignee-attention` (if assigned) or `needs-triage` (if unassigned). - diff --git a/privacy.md b/privacy.md index 8d6af15eeb..3e433d08b1 100644 --- a/privacy.md +++ b/privacy.md @@ -1,5 +1,5 @@ # Data Collection -The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. +The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at . You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. For more information on telemetry implementation see the [developer guide](docs/developer_guide.md#Telemetry). diff --git a/specs/DateTimePicker-Visual-Updates-Spec.md b/specs/DateTimePicker-Visual-Updates-Spec.md index c8d72770ec..e643794ef2 100644 --- a/specs/DateTimePicker-Visual-Updates-Spec.md +++ b/specs/DateTimePicker-Visual-Updates-Spec.md @@ -9,23 +9,23 @@ while also applying a monochromatic colorization effect. This allows the element to appear to be an overlay on top of the other element. `MonochromaticOverlayPresenter` element is similar to several precedents: -* [CompositionMaskBrush](https://docs.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush), +* [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/Windows.UI.Composition.CompositionMaskBrush), which is a brush that gets its content from another (source) brush. -* WPF's [VisualBrush](https://docs.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush), +* WPF's [VisualBrush](https://learn.microsoft.com/dotnet/api/System.Windows.Media.VisualBrush), which uses an element's rendering to draw a brush. A key difference in this new type is that it only renders the portion of the source element which it intersects with in location. This new `MonochromaticOverlayPresenter` will be used in the rendering of the -[DatePicker](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.DatePicker) +[DatePicker](https://learn.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.DatePicker) control (see more info in the Appendix). # API Pages ## MonochromaticOverlayPresenter class -A [Framework Element](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.frameworkelement?view=winui-3.0-preview) +A [Framework Element](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.frameworkelement?view=winui-3.0-preview) which renders another element at the same position (beneath it in the Z-order), while also optionally applying a monochromatic colorization effect. diff --git a/specs/FooterMenuItemTemplate-spec.md b/specs/FooterMenuItemTemplate-spec.md index d9f7af1d49..01c726cb83 100644 --- a/specs/FooterMenuItemTemplate-spec.md +++ b/specs/FooterMenuItemTemplate-spec.md @@ -1,20 +1,20 @@ # Background -The [`NavigationView.FooterMenuItems`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.footermenuitems?view=winui-2.5) property provides a way to place NavigationView items into a bottom-aligned (or right-aligned, if your NavigationView is in top mode) section of a NavigationView. This is distinct from the [`NavigationView.PaneFooter`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.panefooter?view=winui-2.5) property, as only Navigation items should be placed in the Footer menu, while any kind of content can be placed in the PaneFooter. +The [`NavigationView.FooterMenuItems`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.footermenuitems?view=winui-2.5) property provides a way to place NavigationView items into a bottom-aligned (or right-aligned, if your NavigationView is in top mode) section of a NavigationView. This is distinct from the [`NavigationView.PaneFooter`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.panefooter?view=winui-2.5) property, as only Navigation items should be placed in the Footer menu, while any kind of content can be placed in the PaneFooter. Image of a NavigationView with labels pointing to main menu items and footer menu items -Currently, the DataTemplate that's assigned to the [`NavigationView.MenuItemTemplate`](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) property is applied to all Navigation items in the NavigationView. This means that if you add both regular NavigationView menu items and NavigationView footer menu items, they will automatically have the same data template applied. This is an issue as there's no current way to provide a standardized data template for all footer menu items that's separate/different from the data template used for all main menu items. +Currently, the DataTemplate that's assigned to the [`NavigationView.MenuItemTemplate`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) property is applied to all Navigation items in the NavigationView. This means that if you add both regular NavigationView menu items and NavigationView footer menu items, they will automatically have the same data template applied. This is an issue as there's no current way to provide a standardized data template for all footer menu items that's separate/different from the data template used for all main menu items. # Description -In order to apply a data template to all items in the footer menu of your NavigationView, use the `NavigationView.FooterMenuItemTemplate` property. This property is similar to [NavigationView.MenuItemTemplate](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. It takes in a `DataTemplate` and applies that template to any Navigation item placed in the footer menu. +In order to apply a data template to all items in the footer menu of your NavigationView, use the `NavigationView.FooterMenuItemTemplate` property. This property is similar to [NavigationView.MenuItemTemplate](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. It takes in a `DataTemplate` and applies that template to any Navigation item placed in the footer menu. -To apply different data templates to individual Navigation items within your footer menu based on certain criteria, use the `NavigationView.FooterMenuItemTemplateSelector`. This property is similar to the [NavigationView.MenuItemTemplateSelector](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplateselector?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. +To apply different data templates to individual Navigation items within your footer menu based on certain criteria, use the `NavigationView.FooterMenuItemTemplateSelector`. This property is similar to the [NavigationView.MenuItemTemplateSelector](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplateselector?view=winui-2.5), but only applies to items placed in NavigationView's footer menu. The Settings item will not be affected by FooterMenuItemTemplate as it is not technically a part of the FooterMenuItems collection. -The [NavigationView.MenuItemTemplate](https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) will only apply to Navigation items that are placed in the main menu of a NavigationView. +The [NavigationView.MenuItemTemplate](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview.menuitemtemplate?view=winui-2.5) will only apply to Navigation items that are placed in the main menu of a NavigationView. # Examples @@ -53,12 +53,12 @@ The following APIs are members of `NavigationView`. | Name | Description | | - | - | -| FooterMenuItemTemplate | Gets or sets the [DataTemplate](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.datatemplate) used to display each footer menu item. | -| FooterMenuItemTemplateSelector | Gets or sets a reference to a custom [DataTemplateSelector](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.datatemplateselector) logic class. The DataTemplateSelector referenced by this property returns a template to apply to Navigation items placed in the footer menu. +| FooterMenuItemTemplate | Gets or sets the [DataTemplate](https://learn.microsoft.com/uwp/api/windows.ui.xaml.datatemplate) used to display each footer menu item. | +| FooterMenuItemTemplateSelector | Gets or sets a reference to a custom [DataTemplateSelector](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.datatemplateselector) logic class. The DataTemplateSelector referenced by this property returns a template to apply to Navigation items placed in the footer menu. # API Details - + ```csharp [MUX_PREVIEW]