Skip to content

clean up docs in highest level #11035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jay-o-Way wants to merge 1 commit into
base: main
Choose a base branch
from
Open

clean up docs in highest level #11035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
43 changes: 20 additions & 23 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -41,37 +41,34 @@ 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 <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.

### Copying files from other projects

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.
84 changes: 44 additions & 40 deletions CONTRIBUTING_feedback_and_requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,67 +6,71 @@ 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 \<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](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 \<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\>."

- ### 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 \<framework, language, library, technology, etc.\>. Without this, I can't do \<goal\>."

### 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 \<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

- 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?"

- ### 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: "\<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\>."

## Mutual respect

We strive to be respectful & empathetic toward each other, and we extend this to our fantastic 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.

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.
18 changes: 10 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

</br>

## 🖼️ 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.

<p align="center">
<img src="docs/images/winui-gallery.png" alt="WinUI 3 Gallery" width="400"/>
<img src="docs/images/winui-gallery.png" alt="WinUI 3 Gallery" width="400"/>
</p>
<p align="center">
<a style="text-decoration:none" href="https://apps.microsoft.com/detail/9P3JFPWWDZRC?launch=true&mode=full">
Expand All @@ -57,6 +57,7 @@ Make sure to also check out the [WinUI 3 Gallery](https://aka.ms/winui-gallery),
</p>

## 📺 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
Expand All @@ -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

Expand Down
Loading
Loading