From d4ef1ed20af4292757df6d05d31767cb935863b7 Mon Sep 17 00:00:00 2001 From: Kyaa-dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 6 May 2020 08:22:33 -0700 Subject: [PATCH 01/18] Update Contribution Guide --- contributing.md | 295 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 205 insertions(+), 90 deletions(-) diff --git a/contributing.md b/contributing.md index 4156b2effc5..770c97c876d 100644 --- a/contributing.md +++ b/contributing.md @@ -1,117 +1,232 @@ -# Contributing to the Windows Community Toolkit +# Contributing to the Windows Community Toolkit :sparkles::sparkles: + +Welcome to the Contributing page of the Windows Community Toolkit :tada: + +The entire Windows Community Toolkit team would like to say Congratulations for reaching this far and contributing to one of the most exciting and growing projects you have probably encountered. We are beyond excited for you to participate in the community. It is because of the valuable contributors like you that keep the Windows Community Toolkit thriving. Whether you fix any small bug or a major one, any contribution will go a long way to enhance the project. Our team will always be here if you may require any assistance regarding steps to submit the PR, review your work and any project related questions that you are unclear about. + +Once again Welcome aboard and have fun in this adventurous journey of Windows Community Toolkit :raised_hands: + +In the next few steps you will be able to learn how to contribute to this amazing community, but before you proceed any further it is good to understand what Widows Community Toolkit is all about. The foundation of the **Windows Community Toolkit** is simplicity. -A developer should be able to quickly and easily learn to use the API. +A developer should be able to quickly and easily learn to use the API. -Simplicity and a low barrier to entry are must-have features of every API. If you have any second thoughts about the complexity of a design, it is almost always much better to cut the feature from the current release and spend more time to get the design right for the next release. +Simplicity and a low barrier to entry are must-have features of every API. If you have any second thoughts about the complexity of the design, it is almost always much better to cut the feature from the current release and spend more time to get the design right for the next release. You can always add to an API, you cannot ever remove anything from one. If the design does not feel right, and you ship it anyway, you are likely to regret having done so. That's why many of the guidelines of this document are obvious and serve only one purpose: Simplicity. - - [Questions](#question) - - [Issues or Bugs](#issue) - - [Submitting a pull request](#pr) - - [Quality assurance for pull requests for XAML controls](#xaml) - - [General rules](#rules) - - [Naming conventions](#naming) - - [Documentation](#documentation) - - [Files and folders](#files) +Here is how you can contribute to the Windows Community Toolkit. + +- [Questions](#question) +- [Find and Fix Bug](#issue) +- [Creating a Pull Request] +- [Submitting a pull request] +- [Contributing New Feature] +- [Adding Documentation] +- [Improving Documentation] +- [Reviewing PR] +- [Quality assurance for pull requests for XAML controls] +- [General rules] +- [Naming conventions] +- [Documentation] +- [Files and folders] + +## Questions :grey_question: +It is critical to understand the kind of question you might have. Since Windows Community Toolkit receives volumes of issues and feature requests regularly; we want to make sure that every question receives an answer as soon as possible. Therefore, please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. + +There is a much better chance of getting your question answered on StackOverflow where questions should be tagged with the tag windows-community-toolkit. + +If there is any question related to missing documentation, please file an issue instead at Microsoft Docs + +## Find and Fix Bug :bug: +Windows Community Toolkit receives lots of bug report regularly and one of the best ways to contribute to this amazing community is by finding and fixing bugs. If you find any bug, you can help the community by submitting an issue. Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: + +Your contribution of discovering and fixing the bug will be a great achievement to set your footprints in this incredible project. Therefore, any support from the community members will be greatly appreciated and contributed towards the growth of the project. + +Avoid Roadblocks :construction: +The issue you file must fulfill the requirements of Bug report Template to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. + +It is also essential to not create any duplicate issues by following “Things to consider before submitting any bug report requirement” This will mitigate the risk of duplicity and is critical. +Not sure where to start? +If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of good first issue that can be a great entry way to find and fix any issues that best fits your expertise or technical background. -## Questions -Please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. There is a much better chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag `windows-community-toolkit` +Feeling Pro? Besides solving any issues that you find suitable and may fit your understanding there are also some issues that are labeled as help wanted. The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. -## Found a Bug? -If you find a bug, you can help us by -[submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues). Even better, you can -[submit a Pull Request](#pr) with a fix. +It is significant to work collaboratively which makes this amazing platform so unique. This a place where you can meet new people and work together towards building and expanding WCT. The community is encouraged and motivated to fuel the WCT by looking into innovative ideas and be able to provide solutions. -## Submitting a pull request +Things to consider before submitting any bug report :thinking: +:bug: Please make certain to reproduce the issue. It is essential to Identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. + +:bug: It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on Windows Toolkit page and identify the appropriate repository that the bug applies. + +:bug: Do Not open a new issue if it already exists in the repository. Go to the current open issues of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. + +Creating a Pull Request :rocket: +If this is your first time contributing towards Windows Community Toolkit and never created a PR before, do not worry because you are not in this alone. By following Github Help guidelines you will be able to create your first Pull Request. + +Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can Create a Pull Request from fork. + +Anyone with read access can create a Pull Request without forking the Windows Community Toolkit Repository. Here is how you can directly Create a Pull Request. + +It is essential to create changes on different branch especially if it is major change. + +Once the PR is created and submitted, we will be able to see the associated PR issue and will assist and provide feedback if necessary. + +If you are not certain about the Pull Request submitted; our team along with the community members are here to review the work and highlight any changes the PR might require to fulfill its obligation. + +Submitting a Pull Request :rocket: For every contribution, you must: -* test your code with the [supported SDKs](readme.md#supported) -* follow the [quality guidance](#xaml), [general rules](#rules) and [naming convention](#naming) -* target master branch (or an appropriate release branch if appropriate for a bug fix) +• test your code with the supported SDKs +• follow the quality guidance, general rules, and naming convention +• target master branch (or an appropriate release branch if appropriate for a bug fix) +• Follow the Windows Community Toolkit PR Template +• If adding a new feature +o Before starting coding, you should open an issue and start discussing with the community to see if your idea/feature is interesting enough. +o Add or update a sample for the Sample app + If creating a new sample, create a new icon by following the Thumbnail Style Guide and templates +o Add or update unit tests (if applicable) + +PR must be validated by at least two core members before being merged. + +Please make certain that the PR successfully passes all three status check requirements including Toolkit-CI, WIP, license/cla. If it fails and you are aware of the reasoning please fix the error. If you are unaware of the reasoning please escalate by commenting in the PR, and someone from the team will investigate the build error. -* If adding a new feature - * Before starting coding, **you should open an [issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D)** and start discussing with the community to see if your idea/feature is interesting enough. - * Add or update a sample for the [Sample app](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.SampleApp) - * If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets) - * Add or update unit tests (if applicable) +If the PR passes all the requirements above and reviewers have signed off the PR will be merged. -PR has to be validated by at least two core members before being merged. +Once merged, you can get a pre-release package of the toolkit by adding this (Nuget repo | Gallery) to your Visual Studio. -Once merged, you can get a pre-release package of the toolkit by adding this ([Nuget repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your Visual Studio. +Contributing new Feature :mailbox_with_mail: +The best way to support the Windows Community Toolkit is by contributing a new feature. As Windows Community Toolkit is growing and being utilized by many partners and businesses; the demand for new features has been increased tremendously. -### Adding Documentation +• To contribute a feature you can simply create a proposal by selecting Feature Request from the list. +• Fill out the template by providing detailed information to express your proposal. Remember this is the place where the community is looking at something that might like and vote to implement in the project. +• Once the Feature Request is submitted, it will be open for discussion regarding what solution does this feature provide and how it lives up to the ideology of Windows Community Toolkit. If it gets approved by the team, Congratulations :tada: you are just few steps to successfully contributing this amazing feature. +• Proceed to submit a PR of the proposed Feature. +• If the PR contains an error free code and reviewer signs off, the PR will be merged. You may continue to enhance this feature. +• Kudos :medal_sports: you are now officially a contributor to this amazing community. -Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a seperate Pull Request in the [documentation repository](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) (use the *master* branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged.** +Adding Documentation :page_with_curl: +Documentation is required when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the WindowsCommunityToolkitDocs repository (use the master branch). Both Pull Requests (code and docs) must be approved by the core team before either one is merged. Make sure to update both Pull Requests with a link to each other. If adding a new documentation page: -* Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format. -* Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page - -## Quality assurance for pull requests for XAML controls -We encourage developers to follow the following guidances when submitting pull requests for controls: - * Your control must be usable and efficient with keyboard only - * Tab order must be logical - * Focused controls must be visible - * Action must be triggered when hitting Enter key - * Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control - * Add AutomationProperties.Name on all controls to define what the controls purpose (Name is minimum, but there are some other things too that can really help the screen reader). - * Don't use the same Name on two different elements unless they have different control types - * Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control - * Ensure that you have run your xaml file changes through Xaml Styler (version 2.3+), which can be downloaded from [here](https://visualstudiogallery.msdn.microsoft.com/3de2a3c6-def5-42c4-924d-cc13a29ff5b7). Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). - -You can find more information about these topics [here](https://blogs.msdn.microsoft.com/winuiautomation/2015/07/14/building-accessible-windows-universal-apps-introduction) + +• Copy the documentation template and follow the same format. +• Update the Table of Contents to point to the new page + +Improving Documentation :page_with_curl: +As the community is always working on improving Windows Community Toolkit and introducing new features, we always make certain that our documentation is also updated and meets the requirement of all the current features. Therefore, improving documentation will be a great way to contribute to this project. + +Currently all the Windows Community Toolkit Docs are being hosted on WindowsCommunityToolkitDocs repository and the Doc PR template is being followed by the contributors to propose any changes to update the docs for Windows Community Toolkit. + +How the Doc process works? +When opening a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: + +For documentation for new features, please base your fork off the master branch. + +If you have a typo or existing document improvement to an already shipped feature, please base your change off of the live branch. This will allow us to get the change to the published documentation between releases. + +We will periodically merge updates from the live branch to master to keep master in-sync with the published docs. When we make a new release, we will push master to the live branch in order to publish documentation for new features. + +After following the process above, submit the PR and depending on the improvement you are proposing the changes will eventually appear in these links. + +- [Staging review from 'master' branch] **This link is currently only available for Microsoft Employees** + +- [Live site from 'live' branch] + +Reviewing PR :book: +Reviewing PR’s is essential before merging any changes regarding bug fixes, features, doc improvements etc. You can find the current list of PR’s here. + +Pre-requisites: Download Visual Studio 2017 or 2019, Install Windows Community Toolkit Sample App, Install Git, Install Hub + +Steps to review PR + +• Open Command Prompt. +• Locate the place where you want the clone repo to appear by using cd path. +• Go to Windows Community Toolkit repository and click on “Clone or Download” button to copy the URL. +• Paste the link in Command Prompt by following the Hub Command to Clone Windows Community Toolkit. +• Fork the repo by following the command. +• Checkout PR by using hub pr checkout Command +• Open the Visual Studio +• Click on “Open a project or solution” +• Locate the cloned repository folder in the local machine and select .sln file to open the solution. +• You will see the PR checkout branch in the bottom right corner of the Visual Studio page. (By default it should have been on master branch but since the PR checkout command has been performed; therefore, it’s on the branch that is ready to be tested). +• Now run the Microsoft.Toolkit.Uwp.SampleApp and Open Windows Community Toolkit Sample App as well. +• Review and test the changes side by side. +• Once approved signoff by leaving feedback and results. + +:bulb: List of Hub Commands that can be useful to manage Pull Request. + +Overall, it is essential to make sure the PR has an appropriate branch and it does not contradict with any other changes. If it has multiple changes then make certain it is clearly stated in the PR Template with the detailed information and all the requirements of the PR checklist has been fulfilled. + +It is also significant to watch if the PR contains any breaking changes or not. If the PR contains a breaking change, check for the detailed description of the impact and migration path for existing application. + +:rotating_light: Breaking changes are likely to be rejected. + +Quality assurance for pull requests for XAML controls +We encourage developers to follow the following guidelines when submitting pull requests for controls: + +• Your control must be usable and efficient with the keyboard only. +• Tab order must be logical. +• Focused controls must be visible. +• Action must be triggered when hitting the Enter key. +• Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control. +• Add AutomationProperties.Name on all controls to define the control’s purpose (Name is minimum, but there are some other things too that can help the screen reader). +• Don't use the same Name on two different elements unless they have different control types. +• Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. +• Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from here. Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). + +You can find more information about these topics here This is to help as part of our effort to build an accessible toolkit (starting with 1.2) -## General rules - -* DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. -* DO provide good defaults for all values associated with parameters, options, etc. -* DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. -* DO communicate incorrect usage of APIs as soon as possible. -* DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples. -* DO NOT use regions. DO use partial classes instead. -* DO declare static dependency properties at the top of their file. -* DO NOT seal controls. -* DO use extension methods over static methods where possible. -* DO NOT return true or false to give sucess status. Throw exceptions if there was a failure. -* DO use verbs like GET. -* DO NOT use verbs that are not already used like fetch. - -## Accessibility Guideline - -We'll follow this guideline to ensure the basic accessibility features for each control. - -### Color & High Contrast themes -* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. -* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. -### Keyboard -* Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. -* Composite elements must ensure proper inner navigation among the contained elements -* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). -* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. -### Narrator -* Controls must support narrator. - -## Naming conventions -* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). - -## Documentation -* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. -* DO provide great documentation with all APIs. -* DO use readable and self-documenting identifier names. -* DO use consistent naming and terminology. -* DO provide strongly typed APIs. -* DO use verbose identifier names. - -## Files and folders -* DO associate no more than one class per file. -* DO use folders to group classes based on features. +General rules :warning: +• DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. +• DO provide good defaults for all values associated with parameters, options, etc. +• DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. +• DO communicate incorrect usage of APIs as soon as possible. +• DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples. +• DO NOT use regions. DO use partial classes instead. +• DO declare static dependency properties at the top of their file. +• DO NOT seal controls. +• DO use extension methods over static methods where possible. +• DO NOT return true or false to give success status. Throw exceptions if there was a failure. +• DO use verbs like GET. +• DO NOT use verbs that are not already used like fetch. + +Accessibility Guideline :wheelchair: +We'll follow this guideline to ensure the basic accessibility features for each control. + +Color & High Contrast themes +• Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. +• Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. + +Keyboard +• Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. +• Composite elements must ensure proper inner navigation among the contained elements +• Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). +• Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. + +Narrator +• Controls must support the narrator. + +Naming conventions +• We are following the coding guidelines of .NET Core Foundational libraries. + +Documentation :page_with_curl: +• DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. +• DO provide great documentation with all APIs. +• DO use readable and self-documenting identifier names. +• DO use consistent naming and terminology. +• DO provide strongly typed APIs. +• DO use verbose identifier names. + +Files and folders :card_file_box: +• DO associate no more than one class per file. +• DO use folders to group classes based on features. + From 2bd4966b10cce4e98451c353b7db4ba457e78ec5 Mon Sep 17 00:00:00 2001 From: Kyaa-dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Fri, 8 May 2020 14:41:20 -0700 Subject: [PATCH 02/18] Organize and Update links --- contributing.md | 265 ++++++++++++++++++++++++------------------------ 1 file changed, 134 insertions(+), 131 deletions(-) diff --git a/contributing.md b/contributing.md index 770c97c876d..681ae625dd9 100644 --- a/contributing.md +++ b/contributing.md @@ -21,56 +21,58 @@ That's why many of the guidelines of this document are obvious and serve only on Here is how you can contribute to the Windows Community Toolkit. - [Questions](#question) -- [Find and Fix Bug](#issue) -- [Creating a Pull Request] -- [Submitting a pull request] -- [Contributing New Feature] -- [Adding Documentation] -- [Improving Documentation] -- [Reviewing PR] -- [Quality assurance for pull requests for XAML controls] -- [General rules] -- [Naming conventions] -- [Documentation] -- [Files and folders] +- [Find and Fix a Bug](#issue) +- [Creating a Pull Request](#Create-PR) +- [Submitting a pull request](#Submit-PR) +- [Contributing New Feature](#Feature) +- [Adding Documentation](#Adding-Docs) +- [Improving Documentation](#Improve-Docs) +- [Reviewing PR](#Review-PR) +- [Quality assurance for pull requests for XAML controls](#xaml) +- [General rules](#rules) +- [Accessibility](#accessibility) +- [Naming conventions](#naming) +- [Documentation](#documentation) +- [Files and folders](#files) ## Questions :grey_question: It is critical to understand the kind of question you might have. Since Windows Community Toolkit receives volumes of issues and feature requests regularly; we want to make sure that every question receives an answer as soon as possible. Therefore, please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. -There is a much better chance of getting your question answered on StackOverflow where questions should be tagged with the tag windows-community-toolkit. +There is a much better chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. -If there is any question related to missing documentation, please file an issue instead at Microsoft Docs +If there is any question related to missing documentation, please file an issue instead at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). -## Find and Fix Bug :bug: -Windows Community Toolkit receives lots of bug report regularly and one of the best ways to contribute to this amazing community is by finding and fixing bugs. If you find any bug, you can help the community by submitting an issue. Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: +## Find and Fix a Bug :bug: +Windows Community Toolkit receives lots of bug report regularly and one of the best ways to contribute to this amazing community is by finding and fixing bugs. If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new/choose). Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: Your contribution of discovering and fixing the bug will be a great achievement to set your footprints in this incredible project. Therefore, any support from the community members will be greatly appreciated and contributed towards the growth of the project. -Avoid Roadblocks :construction: -The issue you file must fulfill the requirements of Bug report Template to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. +### Avoid Roadblocks :construction: +The issue you file must fulfill the requirements of [Bug report](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) Template to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. It is also essential to not create any duplicate issues by following “Things to consider before submitting any bug report requirement” This will mitigate the risk of duplicity and is critical. -Not sure where to start? -If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of good first issue that can be a great entry way to find and fix any issues that best fits your expertise or technical background. +### Not sure where to start? +If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entry way to find and fix any issues that best fits your expertise or technical background. -Feeling Pro? Besides solving any issues that you find suitable and may fit your understanding there are also some issues that are labeled as help wanted. The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. +### Feeling Pro? +Besides working on any [issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) that you find suitable and may fit your understanding there are also some issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. It is significant to work collaboratively which makes this amazing platform so unique. This a place where you can meet new people and work together towards building and expanding WCT. The community is encouraged and motivated to fuel the WCT by looking into innovative ideas and be able to provide solutions. -Things to consider before submitting any bug report :thinking: -:bug: Please make certain to reproduce the issue. It is essential to Identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. +### Things to consider before submitting any bug report :thinking: +:bug: Please make certain to reproduce the issue. It is essential to Identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. -:bug: It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on Windows Toolkit page and identify the appropriate repository that the bug applies. +:bug: It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. -:bug: Do Not open a new issue if it already exists in the repository. Go to the current open issues of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. +:bug: Do Not open a new issue if it already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. -Creating a Pull Request :rocket: -If this is your first time contributing towards Windows Community Toolkit and never created a PR before, do not worry because you are not in this alone. By following Github Help guidelines you will be able to create your first Pull Request. +## Creating a Pull Request :rocket: +If this is your first time contributing towards Windows Community Toolkit and never created a PR before, do not worry because you are not in this alone. By following the guidelines below you will be able to create your first Pull Request. -Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can Create a Pull Request from fork. +Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). -Anyone with read access can create a Pull Request without forking the Windows Community Toolkit Repository. Here is how you can directly Create a Pull Request. +Anyone with read access can create a Pull Request without forking the Windows Community Toolkit Repository. Here is how you can directly [Create a Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) on the main repository. It is essential to create changes on different branch especially if it is major change. @@ -78,17 +80,17 @@ Once the PR is created and submitted, we will be able to see the associated PR i If you are not certain about the Pull Request submitted; our team along with the community members are here to review the work and highlight any changes the PR might require to fulfill its obligation. -Submitting a Pull Request :rocket: +## Submitting a Pull Request :rocket: For every contribution, you must: -• test your code with the supported SDKs -• follow the quality guidance, general rules, and naming convention -• target master branch (or an appropriate release branch if appropriate for a bug fix) -• Follow the Windows Community Toolkit PR Template -• If adding a new feature -o Before starting coding, you should open an issue and start discussing with the community to see if your idea/feature is interesting enough. -o Add or update a sample for the Sample app - If creating a new sample, create a new icon by following the Thumbnail Style Guide and templates +* test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) +* follow the [quality guidance](#xaml), [general rules](#rules), and [naming convention](#naming) +* target master branch (or an appropriate release branch if appropriate for a bug fix) +* Follow the Windows Community Toolkit [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) +* If adding a new feature +o Before starting coding, you should open an [issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and start discussing with the community to see if your idea/feature is interesting enough. +o Add or update a sample for the [Sample app](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.SampleApp) + If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets) o Add or update unit tests (if applicable) PR must be validated by at least two core members before being merged. @@ -97,136 +99,137 @@ Please make certain that the PR successfully passes all three status check requi If the PR passes all the requirements above and reviewers have signed off the PR will be merged. -Once merged, you can get a pre-release package of the toolkit by adding this (Nuget repo | Gallery) to your Visual Studio. +Once merged, you can get a pre-release package of the toolkit by adding this ([Nuget repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your Visual Studio. -Contributing new Feature :mailbox_with_mail: -The best way to support the Windows Community Toolkit is by contributing a new feature. As Windows Community Toolkit is growing and being utilized by many partners and businesses; the demand for new features has been increased tremendously. +## Contributing new Feature :mailbox_with_mail: +The best way to support the Windows Community Toolkit is by contributing a new feature. As Windows Community Toolkit is growing and being utilized by many partners and businesses; the demand for new features has increased tremendously. -• To contribute a feature you can simply create a proposal by selecting Feature Request from the list. -• Fill out the template by providing detailed information to express your proposal. Remember this is the place where the community is looking at something that might like and vote to implement in the project. -• Once the Feature Request is submitted, it will be open for discussion regarding what solution does this feature provide and how it lives up to the ideology of Windows Community Toolkit. If it gets approved by the team, Congratulations :tada: you are just few steps to successfully contributing this amazing feature. -• Proceed to submit a PR of the proposed Feature. -• If the PR contains an error free code and reviewer signs off, the PR will be merged. You may continue to enhance this feature. -• Kudos :medal_sports: you are now officially a contributor to this amazing community. +* To contribute a new feature you can simply create a proposal by selecting [Feature Request](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new/choose) from the list. +* Fill out the template by providing detailed information to express your proposal. Remember this is the place where the community is looking at something that might like and vote to implement in the project. +* Once the Feature Request is submitted, it will be open for discussion regarding what solution does this feature provide and how it lives up to the ideology of Windows Community Toolkit. If it gets approved by the team, Congratulations! you are just few steps to successfully contributing this amazing feature. +* Proceed to submit a PR of the proposed Feature. +* If the PR contains an error free code and reviewer signs off, the PR will be merged. You may continue to enhance this feature. +* Kudos :medal_sports: you are now officially a contributor to this amazing community. -Adding Documentation :page_with_curl: -Documentation is required when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the WindowsCommunityToolkitDocs repository (use the master branch). Both Pull Requests (code and docs) must be approved by the core team before either one is merged. +### Adding Documentation :page_with_curl: +Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository (use the master branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged**. Make sure to update both Pull Requests with a link to each other. If adding a new documentation page: -• Copy the documentation template and follow the same format. -• Update the Table of Contents to point to the new page +* Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format. +* Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page -Improving Documentation :page_with_curl: +## Improving Documentation :page_with_curl: As the community is always working on improving Windows Community Toolkit and introducing new features, we always make certain that our documentation is also updated and meets the requirement of all the current features. Therefore, improving documentation will be a great way to contribute to this project. -Currently all the Windows Community Toolkit Docs are being hosted on WindowsCommunityToolkitDocs repository and the Doc PR template is being followed by the contributors to propose any changes to update the docs for Windows Community Toolkit. +Currently all the Windows Community Toolkit Docs are being hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository and the [Doc PR template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/.github/PULL_REQUEST_TEMPLATE.md) is being followed by the contributors to propose any changes to update the docs for Windows Community Toolkit. -How the Doc process works? +### How does the Doc process works? When opening a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: For documentation for new features, please base your fork off the master branch. -If you have a typo or existing document improvement to an already shipped feature, please base your change off of the live branch. This will allow us to get the change to the published documentation between releases. +If you have a typo or existing document improvement to an already shipped feature, please base your change off of the [live branch](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/tree/live). This will allow us to get the change to the published documentation between releases. We will periodically merge updates from the live branch to master to keep master in-sync with the published docs. When we make a new release, we will push master to the live branch in order to publish documentation for new features. After following the process above, submit the PR and depending on the improvement you are proposing the changes will eventually appear in these links. -- [Staging review from 'master' branch] **This link is currently only available for Microsoft Employees** +- [Staging review from 'master' branch](https://review.docs.microsoft.com/windows/communitytoolkit/?branch=master) **This link is currently only available for Microsoft Employees** -- [Live site from 'live' branch] +- [Live site from 'live' branch](https://docs.microsoft.com/windows/communitytoolkit) -Reviewing PR :book: -Reviewing PR’s is essential before merging any changes regarding bug fixes, features, doc improvements etc. You can find the current list of PR’s here. +## Reviewing PR :book: +Reviewing PR is essential before merging any changes regarding bug fixes, features, doc improvements etc. You can find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls). -Pre-requisites: Download Visual Studio 2017 or 2019, Install Windows Community Toolkit Sample App, Install Git, Install Hub +Pre-requisites: Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) Steps to review PR - -• Open Command Prompt. -• Locate the place where you want the clone repo to appear by using cd path. -• Go to Windows Community Toolkit repository and click on “Clone or Download” button to copy the URL. -• Paste the link in Command Prompt by following the Hub Command to Clone Windows Community Toolkit. -• Fork the repo by following the command. -• Checkout PR by using hub pr checkout Command -• Open the Visual Studio -• Click on “Open a project or solution” -• Locate the cloned repository folder in the local machine and select .sln file to open the solution. -• You will see the PR checkout branch in the bottom right corner of the Visual Studio page. (By default it should have been on master branch but since the PR checkout command has been performed; therefore, it’s on the branch that is ready to be tested). -• Now run the Microsoft.Toolkit.Uwp.SampleApp and Open Windows Community Toolkit Sample App as well. -• Review and test the changes side by side. -• Once approved signoff by leaving feedback and results. - -:bulb: List of Hub Commands that can be useful to manage Pull Request. - -Overall, it is essential to make sure the PR has an appropriate branch and it does not contradict with any other changes. If it has multiple changes then make certain it is clearly stated in the PR Template with the detailed information and all the requirements of the PR checklist has been fulfilled. + +* Go to [Windows Community Toolkit](https://github.com/windows-toolkit/WindowsCommunityToolkit) repository and click on **“Clone or Download”** button to copy the URL. +* Open Command Prompt. +* Locate the folder where you want the clone repo to appear by using cd path. +* Paste the link in Command Prompt by following the [Hub Command](https://hub.github.com/#developer) to Clone Windows Community Toolkit. +* [Fork](https://hub.github.com/#contributor) the repo by following the command. +* Checkout the PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command. +* Open the Visual Studio. +* Click on “Open a project or solution” +* Locate the cloned repository folder in the local machine and select .sln file to open the solution. +* You will see the PR checkout branch in the bottom right corner of the Visual Studio screen. (By default it should have been on master branch but since the PR checkout command has been performed; therefore, it’s on the selected branch that is ready to be tested). +* Now run the Microsoft.Toolkit.Uwp.SampleApp in Viusal Studio. +* Open the downloaded [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp) as well. +* Review and test the changes side by side. +* Once approved signoff by leaving feedback and results. + + :bulb: List of important [Hub Commands](https://hub.github.com/hub.1.html#commands) that can be useful to manage any Pull Request. + +Overall, it is essential to make sure the PR has an appropriate branch and it does not contradict with any other changes. If it has multiple changes then make certain it is clearly stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) with the detailed information and all the requirements of the PR checklist has been fulfilled. It is also significant to watch if the PR contains any breaking changes or not. If the PR contains a breaking change, check for the detailed description of the impact and migration path for existing application. :rotating_light: Breaking changes are likely to be rejected. -Quality assurance for pull requests for XAML controls +## Quality assurance for pull requests for XAML controls We encourage developers to follow the following guidelines when submitting pull requests for controls: -• Your control must be usable and efficient with the keyboard only. -• Tab order must be logical. -• Focused controls must be visible. -• Action must be triggered when hitting the Enter key. -• Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control. -• Add AutomationProperties.Name on all controls to define the control’s purpose (Name is minimum, but there are some other things too that can help the screen reader). -• Don't use the same Name on two different elements unless they have different control types. -• Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. -• Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from here. Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). +* Your control must be usable and efficient with the keyboard only. +* Tab order must be logical. +* Focused controls must be visible. +* Action must be triggered when hitting the Enter key. +* Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control. +* Add AutomationProperties.Name on all controls to define the control’s purpose (Name is minimum, but there are some other things too that can help the screen reader). +* Don't use the same Name on two different elements unless they have different control types. +* Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. +* Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from [here](https://visualstudiogallery.msdn.microsoft.com/3de2a3c6-def5-42c4-924d-cc13a29ff5b7). Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). -You can find more information about these topics here +You can find more information about these topics [here](https://blogs.msdn.microsoft.com/winuiautomation/2015/07/14/building-accessible-windows-universal-apps-introduction). This is to help as part of our effort to build an accessible toolkit (starting with 1.2) -General rules :warning: -• DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. -• DO provide good defaults for all values associated with parameters, options, etc. -• DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. -• DO communicate incorrect usage of APIs as soon as possible. -• DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples. -• DO NOT use regions. DO use partial classes instead. -• DO declare static dependency properties at the top of their file. -• DO NOT seal controls. -• DO use extension methods over static methods where possible. -• DO NOT return true or false to give success status. Throw exceptions if there was a failure. -• DO use verbs like GET. -• DO NOT use verbs that are not already used like fetch. - -Accessibility Guideline :wheelchair: +## General rules :warning: +* DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. +* DO provide good defaults for all values associated with parameters, options, etc. +* DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. +* DO communicate incorrect usage of APIs as soon as possible. +* DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples. +* DO NOT use regions. DO use partial classes instead. +* DO declare static dependency properties at the top of their file. +* DO NOT seal controls. +* DO use extension methods over static methods where possible. +* DO NOT return true or false to give success status. Throw exceptions if there was a failure. +* DO use verbs like GET. +* DO NOT use verbs that are not already used like fetch. + +## Accessibility Guideline :wheelchair: We'll follow this guideline to ensure the basic accessibility features for each control. -Color & High Contrast themes -• Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. -• Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. - -Keyboard -• Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. -• Composite elements must ensure proper inner navigation among the contained elements -• Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). -• Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. - -Narrator -• Controls must support the narrator. - -Naming conventions -• We are following the coding guidelines of .NET Core Foundational libraries. - -Documentation :page_with_curl: -• DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. -• DO provide great documentation with all APIs. -• DO use readable and self-documenting identifier names. -• DO use consistent naming and terminology. -• DO provide strongly typed APIs. -• DO use verbose identifier names. - -Files and folders :card_file_box: -• DO associate no more than one class per file. -• DO use folders to group classes based on features. +### Color & High Contrast themes +* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. +* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. + +### Keyboard +* Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. +* Composite elements must ensure proper inner navigation among the contained elements +* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). +* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. + +### Narrator +* Controls must support the narrator. + +## Naming conventions +* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). + +## Documentation :page_with_curl: +* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. +* DO provide great documentation with all APIs. +* DO use readable and self-documenting identifier names. +* DO use consistent naming and terminology. +* DO provide strongly typed APIs. +* DO use verbose identifier names. + +## Files and folders :card_file_box: +* DO associate no more than one class per file. +* DO use folders to group classes based on features. From 4bb61c4ea19dd10063996082dadd26e11b46ca83 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 28 Oct 2020 17:31:25 -0700 Subject: [PATCH 03/18] Update contributing.md --- contributing.md | 148 +++++++++++------------------------------------- 1 file changed, 33 insertions(+), 115 deletions(-) diff --git a/contributing.md b/contributing.md index 681ae625dd9..d8a758197e4 100644 --- a/contributing.md +++ b/contributing.md @@ -1,91 +1,55 @@ # Contributing to the Windows Community Toolkit :sparkles::sparkles: -Welcome to the Contributing page of the Windows Community Toolkit :tada: -The entire Windows Community Toolkit team would like to say Congratulations for reaching this far and contributing to one of the most exciting and growing projects you have probably encountered. We are beyond excited for you to participate in the community. It is because of the valuable contributors like you that keep the Windows Community Toolkit thriving. Whether you fix any small bug or a major one, any contribution will go a long way to enhance the project. Our team will always be here if you may require any assistance regarding steps to submit the PR, review your work and any project related questions that you are unclear about. +The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. We are beyond excited for you to participate in the community. It is because of the valuable contributors like you that keep the Windows Community Toolkit thriving. Whether you fix any small bug or a major one, all contribution will go a long way to enhance the project. -Once again Welcome aboard and have fun in this adventurous journey of Windows Community Toolkit :raised_hands: +In the next few steps you will be able to see the glimpse of ways to contribute in this amazing community but for complete and detail oriented content please visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) page :sparkles: :sparkles: -In the next few steps you will be able to learn how to contribute to this amazing community, but before you proceed any further it is good to understand what Widows Community Toolkit is all about. +Here is a list of ways you can contribute to the Windows Community Toolkit. -The foundation of the **Windows Community Toolkit** is simplicity. - -A developer should be able to quickly and easily learn to use the API. - -Simplicity and a low barrier to entry are must-have features of every API. If you have any second thoughts about the complexity of the design, it is almost always much better to cut the feature from the current release and spend more time to get the design right for the next release. - -You can always add to an API, you cannot ever remove anything from one. If the design does not feel right, and you ship it anyway, you are likely to regret having done so. - -That's why many of the guidelines of this document are obvious and serve only one purpose: Simplicity. - -Here is how you can contribute to the Windows Community Toolkit. - -- [Questions](#question) -- [Find and Fix a Bug](#issue) -- [Creating a Pull Request](#Create-PR) -- [Submitting a pull request](#Submit-PR) -- [Contributing New Feature](#Feature) -- [Adding Documentation](#Adding-Docs) -- [Improving Documentation](#Improve-Docs) -- [Reviewing PR](#Review-PR) -- [Quality assurance for pull requests for XAML controls](#xaml) -- [General rules](#rules) -- [Accessibility](#accessibility) -- [Naming conventions](#naming) -- [Documentation](#documentation) -- [Files and folders](#files) - -## Questions :grey_question: -It is critical to understand the kind of question you might have. Since Windows Community Toolkit receives volumes of issues and feature requests regularly; we want to make sure that every question receives an answer as soon as possible. Therefore, please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. +## Questions :grey_question: +Windows Community Toolkit receives volumes of issues regularly and due to the large pool of requests it is extremely difficult to prioritize answers. Therefore, please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. + There is a much better chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. -If there is any question related to missing documentation, please file an issue instead at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). +For missing documentation related question, please file an issue at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). -## Find and Fix a Bug :bug: -Windows Community Toolkit receives lots of bug report regularly and one of the best ways to contribute to this amazing community is by finding and fixing bugs. If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new/choose). Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: +## Fix a Bug :bug: +If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=bug+%3Abug%3A&template=bug_report.md&title=). Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: -Your contribution of discovering and fixing the bug will be a great achievement to set your footprints in this incredible project. Therefore, any support from the community members will be greatly appreciated and contributed towards the growth of the project. - -### Avoid Roadblocks :construction: -The issue you file must fulfill the requirements of [Bug report](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) Template to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. +### Things to consider before submitting any bug report :thinking: -It is also essential to not create any duplicate issues by following “Things to consider before submitting any bug report requirement” This will mitigate the risk of duplicity and is critical. +Please make certain to reproduce the issue. It is essential to identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. -### Not sure where to start? -If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entry way to find and fix any issues that best fits your expertise or technical background. +It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. -### Feeling Pro? -Besides working on any [issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) that you find suitable and may fit your understanding there are also some issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. +Do Not open a new issue if the Duplicate issue already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. -It is significant to work collaboratively which makes this amazing platform so unique. This a place where you can meet new people and work together towards building and expanding WCT. The community is encouraged and motivated to fuel the WCT by looking into innovative ideas and be able to provide solutions. +The issue you file must fulfill the requirements of [Bug report Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. -### Things to consider before submitting any bug report :thinking: -:bug: Please make certain to reproduce the issue. It is essential to Identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. +### Good First Issue :ok_hand: +If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entry way to find and fix any issues that best fits your expertise or technical background. -:bug: It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. -:bug: Do Not open a new issue if it already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. +### Help Wanted :raising_hand: +Besides working on any [issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) that you find suitable and may fit your understanding there are also some issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. -## Creating a Pull Request :rocket: -If this is your first time contributing towards Windows Community Toolkit and never created a PR before, do not worry because you are not in this alone. By following the guidelines below you will be able to create your first Pull Request. +## Create Pull Request :rocket: Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). -Anyone with read access can create a Pull Request without forking the Windows Community Toolkit Repository. Here is how you can directly [Create a Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) on the main repository. +Once you fork the Windows Community Toolkit repo, it is essential to create all changes in the feature branch of your forked repository. If you have the changes in the forked feature branch you can create a Pull Request in the main Windows Community Toolkit where your changes will be reviewed to be merged to the Master. -It is essential to create changes on different branch especially if it is major change. +:warning: **We will not merge the PR to the main repo if your changes are not in the feature branch of your forked repository** :warning: -Once the PR is created and submitted, we will be able to see the associated PR issue and will assist and provide feedback if necessary. -If you are not certain about the Pull Request submitted; our team along with the community members are here to review the work and highlight any changes the PR might require to fulfill its obligation. - -## Submitting a Pull Request :rocket: +## Submit Pull Request :rocket: For every contribution, you must: -* test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) -* follow the [quality guidance](#xaml), [general rules](#rules), and [naming convention](#naming) -* target master branch (or an appropriate release branch if appropriate for a bug fix) +* Test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) +* Follow the [quality guidance](#xaml), [general rules](#rules), and [naming convention](#naming) +* Target master branch (or an appropriate release branch if appropriate for a bug fix) * Follow the Windows Community Toolkit [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) * If adding a new feature o Before starting coding, you should open an [issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and start discussing with the community to see if your idea/feature is interesting enough. @@ -101,17 +65,14 @@ If the PR passes all the requirements above and reviewers have signed off the PR Once merged, you can get a pre-release package of the toolkit by adding this ([Nuget repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your Visual Studio. -## Contributing new Feature :mailbox_with_mail: -The best way to support the Windows Community Toolkit is by contributing a new feature. As Windows Community Toolkit is growing and being utilized by many partners and businesses; the demand for new features has increased tremendously. - -* To contribute a new feature you can simply create a proposal by selecting [Feature Request](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new/choose) from the list. +## Contribute new Feature :mailbox_with_mail: +* To contribute a new feature you can simply create a proposal by selecting [Feature Request](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) from the list. * Fill out the template by providing detailed information to express your proposal. Remember this is the place where the community is looking at something that might like and vote to implement in the project. * Once the Feature Request is submitted, it will be open for discussion regarding what solution does this feature provide and how it lives up to the ideology of Windows Community Toolkit. If it gets approved by the team, Congratulations! you are just few steps to successfully contributing this amazing feature. * Proceed to submit a PR of the proposed Feature. * If the PR contains an error free code and reviewer signs off, the PR will be merged. You may continue to enhance this feature. -* Kudos :medal_sports: you are now officially a contributor to this amazing community. -### Adding Documentation :page_with_curl: +### Add Documentation :page_with_curl: Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository (use the master branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged**. Make sure to update both Pull Requests with a link to each other. @@ -121,9 +82,7 @@ If adding a new documentation page: * Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format. * Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page -## Improving Documentation :page_with_curl: -As the community is always working on improving Windows Community Toolkit and introducing new features, we always make certain that our documentation is also updated and meets the requirement of all the current features. Therefore, improving documentation will be a great way to contribute to this project. - +## Improve Documentation :page_with_curl: Currently all the Windows Community Toolkit Docs are being hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository and the [Doc PR template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/.github/PULL_REQUEST_TEMPLATE.md) is being followed by the contributors to propose any changes to update the docs for Windows Community Toolkit. ### How does the Doc process works? @@ -141,10 +100,9 @@ After following the process above, submit the PR and depending on the improvemen - [Live site from 'live' branch](https://docs.microsoft.com/windows/communitytoolkit) -## Reviewing PR :book: -Reviewing PR is essential before merging any changes regarding bug fixes, features, doc improvements etc. You can find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls). +## Review PR :book: -Pre-requisites: Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) +Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) Steps to review PR @@ -163,15 +121,11 @@ Steps to review PR * Review and test the changes side by side. * Once approved signoff by leaving feedback and results. - :bulb: List of important [Hub Commands](https://hub.github.com/hub.1.html#commands) that can be useful to manage any Pull Request. - Overall, it is essential to make sure the PR has an appropriate branch and it does not contradict with any other changes. If it has multiple changes then make certain it is clearly stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) with the detailed information and all the requirements of the PR checklist has been fulfilled. -It is also significant to watch if the PR contains any breaking changes or not. If the PR contains a breaking change, check for the detailed description of the impact and migration path for existing application. - :rotating_light: Breaking changes are likely to be rejected. -## Quality assurance for pull requests for XAML controls +## Building XAML Controls We encourage developers to follow the following guidelines when submitting pull requests for controls: * Your control must be usable and efficient with the keyboard only. @@ -184,11 +138,7 @@ We encourage developers to follow the following guidelines when submitting pull * Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. * Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from [here](https://visualstudiogallery.msdn.microsoft.com/3de2a3c6-def5-42c4-924d-cc13a29ff5b7). Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). -You can find more information about these topics [here](https://blogs.msdn.microsoft.com/winuiautomation/2015/07/14/building-accessible-windows-universal-apps-introduction). - -This is to help as part of our effort to build an accessible toolkit (starting with 1.2) - -## General rules :warning: +## Coding Style and Conventions :balance_scale: * DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. * DO provide good defaults for all values associated with parameters, options, etc. * DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. @@ -201,35 +151,3 @@ This is to help as part of our effort to build an accessible toolkit (starting w * DO NOT return true or false to give success status. Throw exceptions if there was a failure. * DO use verbs like GET. * DO NOT use verbs that are not already used like fetch. - -## Accessibility Guideline :wheelchair: -We'll follow this guideline to ensure the basic accessibility features for each control. - -### Color & High Contrast themes -* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. -* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. - -### Keyboard -* Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. -* Composite elements must ensure proper inner navigation among the contained elements -* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). -* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. - -### Narrator -* Controls must support the narrator. - -## Naming conventions -* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). - -## Documentation :page_with_curl: -* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. -* DO provide great documentation with all APIs. -* DO use readable and self-documenting identifier names. -* DO use consistent naming and terminology. -* DO provide strongly typed APIs. -* DO use verbose identifier names. - -## Files and folders :card_file_box: -* DO associate no more than one class per file. -* DO use folders to group classes based on features. - From 3ccd75675fe04fde1d5bff61e2fa6cdaff46341e Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Thu, 29 Oct 2020 21:49:41 -0700 Subject: [PATCH 04/18] Update contributing.md --- contributing.md | 109 +++++++++++++++++++----------------------------- 1 file changed, 44 insertions(+), 65 deletions(-) diff --git a/contributing.md b/contributing.md index bfd254b3e7d..252ae65c3c0 100644 --- a/contributing.md +++ b/contributing.md @@ -1,41 +1,25 @@ # Contributing to the Windows Community Toolkit :sparkles::sparkles: +The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. We are beyond excited for you to participate in the community. Any contribution or value addded by you will go a long way to enhance the project. -The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. We are beyond excited for you to participate in the community. It is because of the valuable contributors like you that keep the Windows Community Toolkit thriving. Whether you fix any small bug or a major one, all contribution will go a long way to enhance the project. - -In the next few steps you will be able to see the glimpse of ways to contribute in this amazing community but for complete and detail oriented content please visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) page :sparkles: :sparkles: - -Here is a list of ways you can contribute to the Windows Community Toolkit. +:rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: +In the next few steps you will be able to see the glimpse of ways you can contribute to the Windows Community Toolkit :rocket: ## Questions :grey_question: -Windows Community Toolkit receives volumes of issues regularly and due to the large pool of requests it is extremely difficult to prioritize answers. Therefore, please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. - -There is a much better chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. +Due to the high volume of incoming issues please keep our GitHub issues for bug reports and feature requests. For general questions, there is a higher chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. For missing documentation related question, please file an issue at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). ## Fix a Bug :bug: -If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=bug+%3Abug%3A&template=bug_report.md&title=). Once you submit the issue feel free to start working on the PR and submit a PR. Due to high quantity of requests our community still make certain that these issues are resolved as soon as possible. Therefore, It is imperative that these issues filed receives top priority and it would be even better if you can fix a bug :rocket: - -### Things to consider before submitting any bug report :thinking: - -Please make certain to reproduce the issue. It is essential to identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. - -It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. - -Do Not open a new issue if the Duplicate issue already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. - -The issue you file must fulfill the requirements of [Bug report Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. +If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=bug+%3Abug%3A&template=bug_report.md&title=). Once the issue is filed, feel free to start working on the PR and submit a PR. ### Good First Issue :ok_hand: If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entry way to find and fix any issues that best fits your expertise or technical background. - ### Help Wanted :raising_hand: Besides working on any [issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) that you find suitable and may fit your understanding there are also some issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. - ## Create Pull Request :rocket: Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). @@ -45,7 +29,7 @@ Once you fork the Windows Community Toolkit repo, it is essential to create all ## Submit Pull Request :rocket: -For every contribution, you must: +Before submitting Pull Request, you must: * Test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) * Follow the [quality guidance](#xaml), [general rules](#rules), and [naming convention](#naming) @@ -57,20 +41,13 @@ o Add or update a sample for the [Sample app](https://github.com/windows-toolkit  If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets) o Add or update unit tests (if applicable) -PR must be validated by at least two core members before being merged. +:warning: Please make certain that the PR successfully passes all three status check requirements including Toolkit-CI, WIP, license/cla. If it fails and you are aware of the reasoning please fix the error. If you are unaware of the reasoning please escalate by commenting in the PR, and someone from the team will investigate the build error. :warning: -Please make certain that the PR successfully passes all three status check requirements including Toolkit-CI, WIP, license/cla. If it fails and you are aware of the reasoning please fix the error. If you are unaware of the reasoning please escalate by commenting in the PR, and someone from the team will investigate the build error. - -If the PR passes all the requirements above and reviewers have signed off the PR will be merged. - -Once merged, you can get a pre-release package of the toolkit by adding this ([Nuget repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your Visual Studio. - -## Contribute new Feature :mailbox_with_mail: -* To contribute a new feature you can simply create a proposal by selecting [Feature Request](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) from the list. -* Fill out the template by providing detailed information to express your proposal. Remember this is the place where the community is looking at something that might like and vote to implement in the project. -* Once the Feature Request is submitted, it will be open for discussion regarding what solution does this feature provide and how it lives up to the ideology of Windows Community Toolkit. If it gets approved by the team, Congratulations! you are just few steps to successfully contributing this amazing feature. -* Proceed to submit a PR of the proposed Feature. -* If the PR contains an error free code and reviewer signs off, the PR will be merged. You may continue to enhance this feature. +## Add New Feature :mailbox_with_mail: +* To contribute a new feature, fill out the [Feature Request Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and provide detailed information to express the proposal. +* Once the Feature Request is submitted, it will be open for discussion. +* If it gets approved by the team, proceed to submit a PR of the proposed Feature. +* If the PR contains an error-free code and the reviewer signs off, the PR will be merged. ### Add Documentation :page_with_curl: Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository (use the master branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged**. @@ -83,17 +60,12 @@ If adding a new documentation page: * Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page ## Improve Documentation :page_with_curl: -Currently all the Windows Community Toolkit Docs are being hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository and the [Doc PR template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/.github/PULL_REQUEST_TEMPLATE.md) is being followed by the contributors to propose any changes to update the docs for Windows Community Toolkit. - -### How does the Doc process works? -When opening a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: +Currently all the Windows Community Toolkit Docs are being hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository. Therefore to create changes or opening a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: -For documentation for new features, please base your fork off the master branch. +For documentation regarding introducing new features, please base your fork off the master branch. If you have a typo or existing document improvement to an already shipped feature, please base your change off of the [live branch](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/tree/live). This will allow us to get the change to the published documentation between releases. -We will periodically merge updates from the live branch to master to keep master in-sync with the published docs. When we make a new release, we will push master to the live branch in order to publish documentation for new features. - After following the process above, submit the PR and depending on the improvement you are proposing the changes will eventually appear in these links. - [Staging review from 'master' branch](https://review.docs.microsoft.com/windows/communitytoolkit/?branch=master) **This link is currently only available for Microsoft Employees** @@ -102,31 +74,38 @@ After following the process above, submit the PR and depending on the improvemen ## Review PR :book: -Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) +Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) Steps to review PR -* Go to [Windows Community Toolkit](https://github.com/windows-toolkit/WindowsCommunityToolkit) repository and click on **“Clone or Download”** button to copy the URL. -* Open Command Prompt. -* Locate the folder where you want the clone repo to appear by using cd path. -* Paste the link in Command Prompt by following the [Hub Command](https://hub.github.com/#developer) to Clone Windows Community Toolkit. -* [Fork](https://hub.github.com/#contributor) the repo by following the command. -* Checkout the PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command. -* Open the Visual Studio. -* Click on “Open a project or solution” -* Locate the cloned repository folder in the local machine and select .sln file to open the solution. -* You will see the PR checkout branch in the bottom right corner of the Visual Studio screen. (By default it should have been on master branch but since the PR checkout command has been performed; therefore, it’s on the selected branch that is ready to be tested). -* Now run the Microsoft.Toolkit.Uwp.SampleApp in Viusal Studio. -* Open the downloaded [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp) as well. -* Review and test the changes side by side. -* Once approved signoff by leaving feedback and results. - -Overall, it is essential to make sure the PR has an appropriate branch and it does not contradict with any other changes. If it has multiple changes then make certain it is clearly stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) with the detailed information and all the requirements of the PR checklist has been fulfilled. - -:rotating_light: Breaking changes are likely to be rejected. - -## Building XAML Controls -We encourage developers to follow the following guidelines when submitting pull requests for controls: +* Open Command Prompt or [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab) +* Locate the place where you want the WCT clone to appear by using the cd path. +* Go to [Windows Community Toolkit](https://github.com/windows-toolkit/WindowsCommunityToolkit) repository and click on **Code** button to copy the HTTPS or SSH URL. +* Paste the link in Command Prompt by following the [Hub Command](https://hub.github.com/#developer) to Clone Windows Community Toolkit. +* [Fork](https://hub.github.com/#contributor) the repo by following the command. +* Checkout PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command +* Open the Visual Studio +* Click on “Open a project or solution” +* Locate the cloned repository folder in the local machine and select .sln file to open the solution. +* You will see the PR checkout branch in the bottom right corner of the Visual Studio page. (By default it should have been on the master branch but since the PR checkout command has been performed; therefore, it’s on the branch that is ready to be tested). +* Now run the Microsoft.Toolkit.Uwp.SampleApp and Open [Windows Community Toolkit Sample App](https://www.microsoft.com/en-us/p/windows-community-toolkit-sample-app/9nblggh4tlcq?rtc=1) as well. +* Review and test the changes side by side. +* Once approved signoff by leaving feedback and results. + +Please make certain that PR has an appropriate branch and it does not contradict with any other changes. If there are multiple changes then make certain it is clearly stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) with the detailed information. + +## Things to consider before submitting any bug report :thinking: + +Please make certain to reproduce the issue. It is essential to identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. + +It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. + +Do Not open a new issue if the Duplicate issue already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. + +The issue you file must fulfill the requirements of [Bug report Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. + +## Building XAML Controls :control_knobs: +Follow these guidelines when submitting Pull Requests for controls: * Your control must be usable and efficient with the keyboard only. * Tab order must be logical. @@ -150,4 +129,4 @@ We encourage developers to follow the following guidelines when submitting pull * DO use extension methods over static methods where possible. * DO NOT return true or false to give success status. Throw exceptions if there was a failure. * DO use verbs like GET. -* DO NOT use verbs that are not already used like fetch. \ No newline at end of file +* DO NOT use verbs that are not already used like fetch. From 25734b95fe1f33008b5cf8f3497f92aaa0c182df Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Fri, 30 Oct 2020 13:29:54 -0700 Subject: [PATCH 05/18] Update contributing.md --- contributing.md | 90 ++++++++++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/contributing.md b/contributing.md index 252ae65c3c0..db07b2c985e 100644 --- a/contributing.md +++ b/contributing.md @@ -1,26 +1,25 @@ # Contributing to the Windows Community Toolkit :sparkles::sparkles: -The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. We are beyond excited for you to participate in the community. Any contribution or value addded by you will go a long way to enhance the project. +The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. Any contribution or value added by you will go a long way to enhance the project. -:rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: -In the next few steps you will be able to see the glimpse of ways you can contribute to the Windows Community Toolkit :rocket: +In the next few steps you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit but :rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: -## Questions :grey_question: +## Questions :grey_question: Due to the high volume of incoming issues please keep our GitHub issues for bug reports and feature requests. For general questions, there is a higher chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. For missing documentation related question, please file an issue at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). -## Fix a Bug :bug: +## Fix a Bug :bug: If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=bug+%3Abug%3A&template=bug_report.md&title=). Once the issue is filed, feel free to start working on the PR and submit a PR. -### Good First Issue :ok_hand: -If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programing experience, we have got you covered :boom: WCT have a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entry way to find and fix any issues that best fits your expertise or technical background. +## Good First Issue :ok_hand: +If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programming experience, we have got you covered :boom: WCT has a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entryway to find and fix any issues that best fit your expertise or technical background. -### Help Wanted :raising_hand: -Besides working on any [issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) that you find suitable and may fit your understanding there are also some issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of experience you can also jump in to solve these issues. +## Help Wanted :raising_hand: +WCT has a list of issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of programming experience you can also jump in to solve these issues. -## Create Pull Request :rocket: +## Create Pull Request :rocket: Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Once you fork the Windows Community Toolkit repo, it is essential to create all changes in the feature branch of your forked repository. If you have the changes in the forked feature branch you can create a Pull Request in the main Windows Community Toolkit where your changes will be reviewed to be merged to the Master. @@ -28,11 +27,11 @@ Once you fork the Windows Community Toolkit repo, it is essential to create all :warning: **We will not merge the PR to the main repo if your changes are not in the feature branch of your forked repository** :warning: -## Submit Pull Request :rocket: +## Submit Pull Request :rocket: Before submitting Pull Request, you must: * Test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) -* Follow the [quality guidance](#xaml), [general rules](#rules), and [naming convention](#naming) +* Follow the [quality guidance](#xaml), [coding style and conventions](#conventions), and [naming convention](#naming) * Target master branch (or an appropriate release branch if appropriate for a bug fix) * Follow the Windows Community Toolkit [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) * If adding a new feature @@ -41,15 +40,14 @@ o Add or update a sample for the [Sample app](https://github.com/windows-toolkit  If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets) o Add or update unit tests (if applicable) -:warning: Please make certain that the PR successfully passes all three status check requirements including Toolkit-CI, WIP, license/cla. If it fails and you are aware of the reasoning please fix the error. If you are unaware of the reasoning please escalate by commenting in the PR, and someone from the team will investigate the build error. :warning: -## Add New Feature :mailbox_with_mail: +## Add New Feature :mailbox_with_mail: * To contribute a new feature, fill out the [Feature Request Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and provide detailed information to express the proposal. * Once the Feature Request is submitted, it will be open for discussion. * If it gets approved by the team, proceed to submit a PR of the proposed Feature. * If the PR contains an error-free code and the reviewer signs off, the PR will be merged. -### Add Documentation :page_with_curl: +## Add Documentation :page_with_curl: Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository (use the master branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged**. Make sure to update both Pull Requests with a link to each other. @@ -57,24 +55,24 @@ Make sure to update both Pull Requests with a link to each other. If adding a new documentation page: * Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format. + * Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page -## Improve Documentation :page_with_curl: -Currently all the Windows Community Toolkit Docs are being hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository. Therefore to create changes or opening a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: +## Improve Documentation :page_with_curl: +All the Windows Community Toolkit Docs are hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository. Therefore to open a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: For documentation regarding introducing new features, please base your fork off the master branch. If you have a typo or existing document improvement to an already shipped feature, please base your change off of the [live branch](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/tree/live). This will allow us to get the change to the published documentation between releases. -After following the process above, submit the PR and depending on the improvement you are proposing the changes will eventually appear in these links. +Once the PR is submitted and merged then depending on the improvement you are proposing the changes will eventually appear in these links. - [Staging review from 'master' branch](https://review.docs.microsoft.com/windows/communitytoolkit/?branch=master) **This link is currently only available for Microsoft Employees** - - [Live site from 'live' branch](https://docs.microsoft.com/windows/communitytoolkit) ## Review PR :book: -Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) +Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls) (Make certain that PR has an appropriate branch. If there are multiple changes then make certain it is stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md)), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) Steps to review PR @@ -86,25 +84,14 @@ Steps to review PR * Checkout PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command * Open the Visual Studio * Click on “Open a project or solution” -* Locate the cloned repository folder in the local machine and select .sln file to open the solution. +* Locate the cloned repository folder in the local machine and select the .sln file to open the solution. * You will see the PR checkout branch in the bottom right corner of the Visual Studio page. (By default it should have been on the master branch but since the PR checkout command has been performed; therefore, it’s on the branch that is ready to be tested). * Now run the Microsoft.Toolkit.Uwp.SampleApp and Open [Windows Community Toolkit Sample App](https://www.microsoft.com/en-us/p/windows-community-toolkit-sample-app/9nblggh4tlcq?rtc=1) as well. * Review and test the changes side by side. * Once approved signoff by leaving feedback and results. + -Please make certain that PR has an appropriate branch and it does not contradict with any other changes. If there are multiple changes then make certain it is clearly stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) with the detailed information. - -## Things to consider before submitting any bug report :thinking: - -Please make certain to reproduce the issue. It is essential to identify the issue and gather more data to be certain if it is a bug or not. It might be a simple fix and can be resolved earlier than expected. - -It is essential to open the issue in an appropriate Windows Community Toolkit repository by clicking on [Windows Toolkit](https://github.com/windows-toolkit) page and identify the appropriate repository that the bug applies. - -Do Not open a new issue if the Duplicate issue already exists in the repository. Go to the current [open issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) of the repository, and perform a search by applying the keyword in the search area. This method should query the result and provide the results of relevant open issues. - -The issue you file must fulfill the requirements of [Bug report Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) to provide greater insight and understanding of the issue. By providing detailed information the issue will be investigated and resolved in a timely manner. - -## Building XAML Controls :control_knobs: +## Building XAML Controls :control_knobs: Follow these guidelines when submitting Pull Requests for controls: * Your control must be usable and efficient with the keyboard only. @@ -117,7 +104,7 @@ Follow these guidelines when submitting Pull Requests for controls: * Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. * Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from [here](https://visualstudiogallery.msdn.microsoft.com/3de2a3c6-def5-42c4-924d-cc13a29ff5b7). Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). -## Coding Style and Conventions :balance_scale: +## Coding Style and Conventions :balance_scale: * DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. * DO provide good defaults for all values associated with parameters, options, etc. * DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. @@ -130,3 +117,36 @@ Follow these guidelines when submitting Pull Requests for controls: * DO NOT return true or false to give success status. Throw exceptions if there was a failure. * DO use verbs like GET. * DO NOT use verbs that are not already used like fetch. + +## Accessibility Guideline + +Basic accessibility features for each control. + +### Color & High Contrast themes +* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. +* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. +### Keyboard +* Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. +* Composite elements must ensure proper inner navigation among the contained elements +* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). +* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. +### Narrator +* Controls must support the narrator. + +## Naming conventions +* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). + +## Documentation +* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. +* DO provide great documentation with all APIs. +* DO use readable and self-documenting identifier names. +* DO use consistent naming and terminology. +* DO provide strongly typed APIs. +* DO use verbose identifier names. + +## Files and folders +* DO associate no more than one class per file. +* DO use folders to group classes based on features. + + +:rotating_light: **Please visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) to view complete and detail-oriented content of this page** :rotating_light: From 55d6b2c3e2f830820b63132e8889d4e994948185 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Fri, 30 Oct 2020 14:17:51 -0700 Subject: [PATCH 06/18] Update contributing.md --- contributing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index db07b2c985e..f32c5aa6ee8 100644 --- a/contributing.md +++ b/contributing.md @@ -1,9 +1,10 @@ # Contributing to the Windows Community Toolkit :sparkles::sparkles: -The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. Any contribution or value added by you will go a long way to enhance the project. +The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. Any contribution or value added will go a long way to enhance the project. +In the next few steps you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit -In the next few steps you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit but :rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: +:rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: ## Questions :grey_question: Due to the high volume of incoming issues please keep our GitHub issues for bug reports and feature requests. For general questions, there is a higher chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. From ebe9787be1026d0a7ce8472396c1e9259f0b7172 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Tue, 3 Nov 2020 10:46:23 -0800 Subject: [PATCH 07/18] Apply suggestions from code review Co-authored-by: Michael Hawker MSFT (XAML Llama) <24302614+michael-hawker@users.noreply.github.com> --- contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing.md b/contributing.md index f32c5aa6ee8..84d92f30173 100644 --- a/contributing.md +++ b/contributing.md @@ -1,10 +1,10 @@ # Contributing to the Windows Community Toolkit :sparkles::sparkles: -The Windows Community Toolkit team is delighted to welcome you for exhibiting interest in contributing to one of the most exhilarating and growing projects. Any contribution or value added will go a long way to enhance the project. +Thank you for exhibiting interest in contributing to the Windows Community Toolkit. The team is delighted to welcome you onboard to our exciting and growing project. Any contribution or value added go a long way to enhance the project! In the next few steps you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit -:rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: +:rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: ## Questions :grey_question: Due to the high volume of incoming issues please keep our GitHub issues for bug reports and feature requests. For general questions, there is a higher chance of getting your question answered on [StackOverflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag windows-community-toolkit. From 85f50b118424f90628e646c936c4c7f96d4675fb Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Tue, 3 Nov 2020 14:19:42 -0800 Subject: [PATCH 08/18] Update contributing.md --- contributing.md | 116 +++--------------------------------------------- 1 file changed, 6 insertions(+), 110 deletions(-) diff --git a/contributing.md b/contributing.md index 84d92f30173..e1ce5a07551 100644 --- a/contributing.md +++ b/contributing.md @@ -28,18 +28,9 @@ Once you fork the Windows Community Toolkit repo, it is essential to create all :warning: **We will not merge the PR to the main repo if your changes are not in the feature branch of your forked repository** :warning: -## Submit Pull Request :rocket: -Before submitting Pull Request, you must: +## Submit or Review Pull Request :rocket: -* Test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported) -* Follow the [quality guidance](#xaml), [coding style and conventions](#conventions), and [naming convention](#naming) -* Target master branch (or an appropriate release branch if appropriate for a bug fix) -* Follow the Windows Community Toolkit [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md) -* If adding a new feature -o Before starting coding, you should open an [issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and start discussing with the community to see if your idea/feature is interesting enough. -o Add or update a sample for the [Sample app](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.SampleApp) - If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets) -o Add or update unit tests (if applicable) +Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it require to Submit or Review Pull Request. ## Add New Feature :mailbox_with_mail: @@ -48,106 +39,11 @@ o Add or update unit tests (if applicable) * If it gets approved by the team, proceed to submit a PR of the proposed Feature. * If the PR contains an error-free code and the reviewer signs off, the PR will be merged. -## Add Documentation :page_with_curl: -Documentation is **required** when adding, removing, or updating a control or an API. To update the documentation, you must submit a separate Pull Request in the [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository (use the master branch). **Both Pull Requests (code and docs) must be approved by the core team before either one is merged**. +## Add or Improve Documentation :page_with_curl: -Make sure to update both Pull Requests with a link to each other. +Due to the multiple steps invovled to add or improve documents; it is required to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) to follow contribution guidelines. -If adding a new documentation page: - -* Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format. - -* Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page - -## Improve Documentation :page_with_curl: -All the Windows Community Toolkit Docs are hosted on [WindowsCommunityToolkitDocs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs) repository. Therefore to open a Pull Request, start by forking this repository. Then, based on the type of change you're making you'll need to create a new branch from either the `master` or `live` branches: - -For documentation regarding introducing new features, please base your fork off the master branch. - -If you have a typo or existing document improvement to an already shipped feature, please base your change off of the [live branch](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/tree/live). This will allow us to get the change to the published documentation between releases. - -Once the PR is submitted and merged then depending on the improvement you are proposing the changes will eventually appear in these links. - -- [Staging review from 'master' branch](https://review.docs.microsoft.com/windows/communitytoolkit/?branch=master) **This link is currently only available for Microsoft Employees** -- [Live site from 'live' branch](https://docs.microsoft.com/windows/communitytoolkit) - -## Review PR :book: - -Pre-requisites: Find the current list of PR’s [here](https://github.com/windows-toolkit/WindowsCommunityToolkit/pulls) (Make certain that PR has an appropriate branch. If there are multiple changes then make certain it is stated in the [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md)), Download Visual Studio 2017 or 2019, Install [Windows Community Toolkit Sample App](http://aka.ms/uwptoolkitapp), [Install Git](https://github.com/github/hub#installation), [Install Hub](https://hub.github.com/#install) - -Steps to review PR - -* Open Command Prompt or [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab) -* Locate the place where you want the WCT clone to appear by using the cd path. -* Go to [Windows Community Toolkit](https://github.com/windows-toolkit/WindowsCommunityToolkit) repository and click on **Code** button to copy the HTTPS or SSH URL. -* Paste the link in Command Prompt by following the [Hub Command](https://hub.github.com/#developer) to Clone Windows Community Toolkit. -* [Fork](https://hub.github.com/#contributor) the repo by following the command. -* Checkout PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command -* Open the Visual Studio -* Click on “Open a project or solution” -* Locate the cloned repository folder in the local machine and select the .sln file to open the solution. -* You will see the PR checkout branch in the bottom right corner of the Visual Studio page. (By default it should have been on the master branch but since the PR checkout command has been performed; therefore, it’s on the branch that is ready to be tested). -* Now run the Microsoft.Toolkit.Uwp.SampleApp and Open [Windows Community Toolkit Sample App](https://www.microsoft.com/en-us/p/windows-community-toolkit-sample-app/9nblggh4tlcq?rtc=1) as well. -* Review and test the changes side by side. -* Once approved signoff by leaving feedback and results. -## Building XAML Controls :control_knobs: -Follow these guidelines when submitting Pull Requests for controls: - -* Your control must be usable and efficient with the keyboard only. -* Tab order must be logical. -* Focused controls must be visible. -* Action must be triggered when hitting the Enter key. -* Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control. -* Add AutomationProperties.Name on all controls to define the control’s purpose (Name is minimum, but there are some other things too that can help the screen reader). -* Don't use the same Name on two different elements unless they have different control types. -* Use Narrator Dev mode (Launch Narrator [WinKey+Enter], then CTRL+F12) to test the screen reader experience. Is the information sufficient, meaningful and helps the user navigate and understand your control. -* Ensure that you have run your XAML file changes through Xaml Styler (version 2.3+), which can be downloaded from [here](https://visualstudiogallery.msdn.microsoft.com/3de2a3c6-def5-42c4-924d-cc13a29ff5b7). Do not worry about the settings for this as they are set at the project level (settings.xamlstyler). - -## Coding Style and Conventions :balance_scale: -* DO NOT require that users perform any extensive initialization before they can start programming basic scenarios. -* DO provide good defaults for all values associated with parameters, options, etc. -* DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. -* DO communicate incorrect usage of APIs as soon as possible. -* DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples. -* DO NOT use regions. DO use partial classes instead. -* DO declare static dependency properties at the top of their file. -* DO NOT seal controls. -* DO use extension methods over static methods where possible. -* DO NOT return true or false to give success status. Throw exceptions if there was a failure. -* DO use verbs like GET. -* DO NOT use verbs that are not already used like fetch. - -## Accessibility Guideline - -Basic accessibility features for each control. - -### Color & High Contrast themes -* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running. -* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it. -### Keyboard -* Controls must support keyboard navigation (tabs and arrow keys), the tab order must be the same as the UI and non-interactive elements mustn't be focusable. -* Composite elements must ensure proper inner navigation among the contained elements -* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space). -* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle. -### Narrator -* Controls must support the narrator. - -## Naming conventions -* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md). - -## Documentation -* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive. -* DO provide great documentation with all APIs. -* DO use readable and self-documenting identifier names. -* DO use consistent naming and terminology. -* DO provide strongly typed APIs. -* DO use verbose identifier names. - -## Files and folders -* DO associate no more than one class per file. -* DO use folders to group classes based on features. - - -:rotating_light: **Please visit [Windows Community Toolkit Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) to view complete and detail-oriented content of this page** :rotating_light: +# Thank You :heart::heart: +**Thank you so much for participating and contributing in this amazing project. We hope you continue to find yourself a strong asset to the Windows Community Toolkit and always find this platform highly reliable.** From eebb6aead5dcc7614df2e7753da25e242d10ce18 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Tue, 3 Nov 2020 17:00:16 -0800 Subject: [PATCH 09/18] Update contributing.md --- contributing.md | 36 +++++++++++++----------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/contributing.md b/contributing.md index e1ce5a07551..e84df22fa8d 100644 --- a/contributing.md +++ b/contributing.md @@ -2,7 +2,7 @@ Thank you for exhibiting interest in contributing to the Windows Community Toolkit. The team is delighted to welcome you onboard to our exciting and growing project. Any contribution or value added go a long way to enhance the project! -In the next few steps you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit +In the next few steps, you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit. :rotating_light: **It is highly recommended to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) where you can find complete and detail-oriented content of this page** :rotating_light: @@ -11,29 +11,16 @@ Due to the high volume of incoming issues please keep our GitHub issues for bug For missing documentation related question, please file an issue at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). -## Fix a Bug :bug: +## Fix a Bug :bug: If you find any bug, you can help the community by [submitting an issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=bug+%3Abug%3A&template=bug_report.md&title=). Once the issue is filed, feel free to start working on the PR and submit a PR. -## Good First Issue :ok_hand: +## Good First Issue :ok_hand: If this is your first time contributing to the Windows Community Toolkit and do not have advanced level programming experience, we have got you covered :boom: WCT has a list of [good first issue](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/good%20first%20issue%20%3Aok_hand%3A) that can be a great entryway to find and fix any issues that best fit your expertise or technical background. -## Help Wanted :raising_hand: -WCT has a list of issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in this list of issues can vary but if you have an advanced level of programming experience you can also jump in to solve these issues. +## Help Wanted :raising_hand: +WCT has a list of issues that are labeled as [help wanted](https://github.com/windows-toolkit/WindowsCommunityToolkit/labels/help%20wanted%20%3Araising_hand%3A). The level of complexity in the list can vary but if you have an advanced level of programming experience, feel free to jump in to solve these issues. -## Create Pull Request :rocket: -Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). - -Once you fork the Windows Community Toolkit repo, it is essential to create all changes in the feature branch of your forked repository. If you have the changes in the forked feature branch you can create a Pull Request in the main Windows Community Toolkit where your changes will be reviewed to be merged to the Master. - -:warning: **We will not merge the PR to the main repo if your changes are not in the feature branch of your forked repository** :warning: - - -## Submit or Review Pull Request :rocket: - -Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it require to Submit or Review Pull Request. - - -## Add New Feature :mailbox_with_mail: +## Add New Feature :mailbox_with_mail: * To contribute a new feature, fill out the [Feature Request Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues/new?assignees=&labels=feature+request+%3Amailbox_with_mail%3A&template=feature_request.md&title=%5BFeature%5D) and provide detailed information to express the proposal. * Once the Feature Request is submitted, it will be open for discussion. * If it gets approved by the team, proceed to submit a PR of the proposed Feature. @@ -41,9 +28,12 @@ Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detai ## Add or Improve Documentation :page_with_curl: -Due to the multiple steps invovled to add or improve documents; it is required to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) to follow contribution guidelines. +Due to the involvement of multiple steps to add or improve documents; it is required to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) and follow contribution guidelines. + + ## Create, Submit or Review Pull Request :rocket: +Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Once you fork the Windows Community Toolkit repo, it is essential to create all changes in the feature branch of your forked repository. If you have the changes in the forked feature branch, you can then create a Pull Request in the main Windows Community Toolkit. - +Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it requires to Submit or Review Pull Request. -# Thank You :heart::heart: -**Thank you so much for participating and contributing in this amazing project. We hope you continue to find yourself a strong asset to the Windows Community Toolkit and always find this platform highly reliable.** +# ThankYou :heart::heart: +**Thank you so much for contributing to this amazing project. We hope you will continue to add value and find yourself as a highly reliable source to the Windows Community Toolkit** From 07bccaa19510a2f3c0368b5e6ff98927030cba89 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 4 Nov 2020 12:28:59 -0800 Subject: [PATCH 10/18] Update readme.md --- readme.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/readme.md b/readme.md index 8648a6e5700..b1976d5125d 100644 --- a/readme.md +++ b/readme.md @@ -25,11 +25,7 @@ All documentation for the toolkit is hosted on [Microsoft Docs](https://docs.mic Want to see the toolkit in action before jumping into the code? Download and play with the [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9nblggh4tlcq) from the Store. ## NuGet Packages -NuGet is a standard package manager for .NET applications which is built into Visual Studio. To open the UI, from your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* . Enter one of the package names below to search for it online. - -Once you do a search, you should see a list similar to the one below (versions may be different, but names should be the same). - -![nuget packages](githubresources/images/NugetPackages.png "Nuget Packages") +NuGet is a standard package manager for .NET applications which is built into Visual Studio. To open the UI, from your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names below to search for it online. | NuGet Package Name | Description | | --- | --- | @@ -66,7 +62,7 @@ The following dependencies are required for building the Windows Community Toolk * [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/download/visual-studio-sdks) ## Contributing -Do you want to contribute? Here are our [contribution guidelines](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/contributing.md). +Do you want to contribute? Checkout our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page. ## Principles * Principle **#1**: The toolkit will be kept simple. From e4d3800097620e18cfec67cb9ad6c2ee112e82ba Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 4 Nov 2020 13:27:51 -0800 Subject: [PATCH 11/18] Update readme.md --- readme.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/readme.md b/readme.md index b1976d5125d..7f4fbd4aa39 100644 --- a/readme.md +++ b/readme.md @@ -15,16 +15,16 @@ The Windows Community Toolkit is a collection of helper functions, custom contro | Production | rel/6.1.0 | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=rel/6.1.0)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10&branchName=rel/6.1.0) | [![NuGet](https://img.shields.io/nuget/v/Microsoft.Toolkit.Uwp.svg)](https://www.nuget.org/profiles/Microsoft.Toolkit) | | Pre-release beta testing | master | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=master)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10) | [![MyGet](https://img.shields.io/dotnet.myget/uwpcommunitytoolkit/vpre/Microsoft.Toolkit.Uwp.svg)](https://dotnet.myget.org/gallery/uwpcommunitytoolkit) | -## Getting Started -Please read the [getting Started with the Windows Community Toolkit](https://docs.microsoft.com/windows/communitytoolkit/getting-started) page for more detailed information about using the toolkit. +## Getting Started :raised_hands: +Please read the [Getting Started with the Windows Community Toolkit](https://docs.microsoft.com/windows/communitytoolkit/getting-started) page for more detailed information about using the toolkit. -## Documentation +## Documentation :pencil: All documentation for the toolkit is hosted on [Microsoft Docs](https://docs.microsoft.com/windows/communitytoolkit/). All API documentation can be found at the [.NET API Browser](https://docs.microsoft.com/dotnet/api/?view=win-comm-toolkit-dotnet-stable). -## Windows Community Toolkit Sample App +## Windows Community Toolkit Sample App :briefcase: Want to see the toolkit in action before jumping into the code? Download and play with the [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9nblggh4tlcq) from the Store. -## NuGet Packages +## NuGet Packages :package: NuGet is a standard package manager for .NET applications which is built into Visual Studio. To open the UI, from your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names below to search for it online. | NuGet Package Name | Description | @@ -45,14 +45,14 @@ NuGet is a standard package manager for .NET applications which is built into Vi | Microsoft.Toolkit.Uwp.Connectivity | API helpers such as BluetoothLEHelper and Networking | | Microsoft.Toolkit.Uwp.DeveloperTools | XAML user controls and services to help developer building their app | -## Features +## Features :mailbox: The [Features list](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md#controls) refers to all the currently available features that can be found in the Windows Community Toolkit. Most features should work with the October 2018 Update (1809) SDK 17763 and above; however, refer to specific documentation on each feature for more information. ## Feedback and Requests Please use [GitHub Issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) for bug reports and feature requests. For general questions and support, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag `windows-community-toolkit`. -## Required Dependencies +## Required Dependencies :pushpin: The following dependencies are required for building the Windows Community Toolkit repo and sample app: * [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) with UWP and .NET workloads @@ -61,10 +61,10 @@ The following dependencies are required for building the Windows Community Toolk * [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/visual-studio-sdks) * [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/download/visual-studio-sdks) -## Contributing -Do you want to contribute? Checkout our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page. +## Contributing :rocket: +Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page. -## Principles +## Principles :ballot_box_with_check: * Principle **#1**: The toolkit will be kept simple. * Principle **#2**: As soon as a comparable feature is available in the Windows SDK for Windows 10, it will be marked as deprecated. * Principle **#3**: All features will be supported for two Windows SDK for Windows 10 release cycles or until another principle supersedes it. @@ -73,7 +73,7 @@ This project has adopted the code of conduct defined by the [Contributor Covenan to clarify expected behavior in our community. For more information see the [.NET Foundation Code of Conduct](CODE_OF_CONDUCT.md). -## Roadmap +## Roadmap :earth_americas: Read what we [plan for next iterations](https://github.com/windows-toolkit/WindowsCommunityToolkit/milestones), and feel free to ask questions. By adding this ([NuGet repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your NuGet sources in Visual Studio, you can also get pre-release packages of upcoming versions. From cca5b394aebfca4a168c985079d1c021b8360804 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 4 Nov 2020 14:08:40 -0800 Subject: [PATCH 12/18] Update readme.md --- readme.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/readme.md b/readme.md index 7f4fbd4aa39..b74a176eee7 100644 --- a/readme.md +++ b/readme.md @@ -1,15 +1,8 @@ ---- -topic: sample -languages: -- csharp -products: -- windows ---- # Windows Community Toolkit The Windows Community Toolkit is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows 10. -## Build Status +## Build Status :building_construction: | Target | Branch | Status | Recommended package version | | ------ | ------ | ------ | ------ | | Production | rel/6.1.0 | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=rel/6.1.0)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10&branchName=rel/6.1.0) | [![NuGet](https://img.shields.io/nuget/v/Microsoft.Toolkit.Uwp.svg)](https://www.nuget.org/profiles/Microsoft.Toolkit) | @@ -48,10 +41,6 @@ NuGet is a standard package manager for .NET applications which is built into Vi ## Features :mailbox: The [Features list](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md#controls) refers to all the currently available features that can be found in the Windows Community Toolkit. Most features should work with the October 2018 Update (1809) SDK 17763 and above; however, refer to specific documentation on each feature for more information. -## Feedback and Requests -Please use [GitHub Issues](https://github.com/windows-toolkit/WindowsCommunityToolkit/issues) for bug reports and feature requests. -For general questions and support, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/windows-community-toolkit) where questions should be tagged with the tag `windows-community-toolkit`. - ## Required Dependencies :pushpin: The following dependencies are required for building the Windows Community Toolkit repo and sample app: @@ -61,8 +50,8 @@ The following dependencies are required for building the Windows Community Toolk * [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/visual-studio-sdks) * [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/download/visual-studio-sdks) -## Contributing :rocket: -Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page. +## Contribution :rocket: +Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page to learn more about contribution and guidelines. ## Principles :ballot_box_with_check: * Principle **#1**: The toolkit will be kept simple. From 5cb240c1d9f4123aa0f40bb856c9b70512a789b8 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 4 Nov 2020 15:04:36 -0800 Subject: [PATCH 13/18] Update readme.md --- readme.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/readme.md b/readme.md index b74a176eee7..137c3fb963b 100644 --- a/readme.md +++ b/readme.md @@ -1,8 +1,7 @@ -# Windows Community Toolkit +# Windows Community Toolkit :briefcase: The Windows Community Toolkit is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows 10. -## Build Status :building_construction: | Target | Branch | Status | Recommended package version | | ------ | ------ | ------ | ------ | | Production | rel/6.1.0 | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=rel/6.1.0)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10&branchName=rel/6.1.0) | [![NuGet](https://img.shields.io/nuget/v/Microsoft.Toolkit.Uwp.svg)](https://www.nuget.org/profiles/Microsoft.Toolkit) | @@ -14,7 +13,7 @@ Please read the [Getting Started with the Windows Community Toolkit](https://doc ## Documentation :pencil: All documentation for the toolkit is hosted on [Microsoft Docs](https://docs.microsoft.com/windows/communitytoolkit/). All API documentation can be found at the [.NET API Browser](https://docs.microsoft.com/dotnet/api/?view=win-comm-toolkit-dotnet-stable). -## Windows Community Toolkit Sample App :briefcase: +## Windows Community Toolkit Sample App :iphone: Want to see the toolkit in action before jumping into the code? Download and play with the [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9nblggh4tlcq) from the Store. ## NuGet Packages :package: @@ -53,19 +52,15 @@ The following dependencies are required for building the Windows Community Toolk ## Contribution :rocket: Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page to learn more about contribution and guidelines. -## Principles :ballot_box_with_check: -* Principle **#1**: The toolkit will be kept simple. -* Principle **#2**: As soon as a comparable feature is available in the Windows SDK for Windows 10, it will be marked as deprecated. -* Principle **#3**: All features will be supported for two Windows SDK for Windows 10 release cycles or until another principle supersedes it. - -This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/) -to clarify expected behavior in our community. -For more information see the [.NET Foundation Code of Conduct](CODE_OF_CONDUCT.md). - ## Roadmap :earth_americas: Read what we [plan for next iterations](https://github.com/windows-toolkit/WindowsCommunityToolkit/milestones), and feel free to ask questions. By adding this ([NuGet repo](https://dotnet.myget.org/F/uwpcommunitytoolkit/api/v3/index.json) | [Gallery](https://dotnet.myget.org/gallery/uwpcommunitytoolkit)) to your NuGet sources in Visual Studio, you can also get pre-release packages of upcoming versions. +## Code of Conduct :page_facing_up: +This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/) +to clarify expected behavior in our community. +For more information see the [.NET Foundation Code of Conduct](CODE_OF_CONDUCT.md). + ## .NET Foundation This project is supported by the [.NET Foundation](http://dotnetfoundation.org). From 75339749dd688e2b7a7531e055aee3a48f9d70f2 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Wed, 4 Nov 2020 16:59:25 -0800 Subject: [PATCH 14/18] Update readme.md --- readme.md | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/readme.md b/readme.md index 137c3fb963b..b8516f03f45 100644 --- a/readme.md +++ b/readme.md @@ -17,25 +17,7 @@ All documentation for the toolkit is hosted on [Microsoft Docs](https://docs.mic Want to see the toolkit in action before jumping into the code? Download and play with the [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9nblggh4tlcq) from the Store. ## NuGet Packages :package: -NuGet is a standard package manager for .NET applications which is built into Visual Studio. To open the UI, from your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names below to search for it online. - -| NuGet Package Name | Description | -| --- | --- | -| Microsoft.Toolkit | .NET Standard NuGet package containing common code | -| Microsoft.Toolkit.HighPerformance | .NET Standard and .NET Core NuGet package with performance oriented helpers, extensions, etc. | -| Microsoft.Toolkit.Parsers | .NET Standard NuGet package containing cross-platform parsers, such as Markdown | -| Microsoft.Toolkit.Services | .NET Standard NuGet package containing cross-platform services helpers, such as LinkedIn, Microsoft Graph, Twitter and more | -| Microsoft.Toolkit.Uwp | Main NuGet package includes code only helpers such as Colors conversion tool, Storage file handling, a Stream helper class, etc. | -| Microsoft.Toolkit.Uwp.Notifications | Notifications Package - Generate tile, toast, and badge notifications for Windows 10 via code. Includes intellisense support to avoid having to use the XML syntax | -| Microsoft.Toolkit.Uwp.UI | UI Packages - XAML converters, Visual tree extensions, and other extensions and helpers for your XAML UI | -| Microsoft.Toolkit.Uwp.UI.Animations | Animations and Composition behaviors such as Blur, Fade, Rotate, etc. | -| Microsoft.Toolkit.Uwp.UI.Controls | XAML Controls such as RadialGauge, RangeSelector, etc. | -| Microsoft.Toolkit.Uwp.UI.Controls.DataGrid | XAML DataGrid control | -| Microsoft.Toolkit.Uwp.UI.Controls.Layout | XAML layout controls such as WrapLayout, StaggeredLayout, etc. | -| Microsoft.Toolkit.Uwp.UI.Lottie | Library for rendering Adobe AfterEffects animations natively in Windows apps | -| Microsoft.Toolkit.Uwp.UI.Media | Brushes, Win2D/Composition effects, and helpers to create visual effects | -| Microsoft.Toolkit.Uwp.Connectivity | API helpers such as BluetoothLEHelper and Networking | -| Microsoft.Toolkit.Uwp.DeveloperTools | XAML user controls and services to help developer building their app | +NuGet is a standard package manager for .NET applications which is built into Visual Studio. From your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names mentioned in [Windows Community Toolkit Nuget Packages](https://docs.microsoft.com/en-us/windows/communitytoolkit/nuget-packages) table to search for it online. ## Features :mailbox: The [Features list](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md#controls) refers to all the currently available features that can be found in the Windows Community Toolkit. Most features should work with the October 2018 Update (1809) SDK 17763 and above; however, refer to specific documentation on each feature for more information. From dad1747124c2968e6fb999329e0faf05fa200177 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Thu, 5 Nov 2020 13:48:03 -0800 Subject: [PATCH 15/18] Update readme.md --- readme.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/readme.md b/readme.md index b8516f03f45..004ecd17d2f 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,5 @@ -# Windows Community Toolkit :briefcase: +# Windows Community Toolkit :toolbox: The Windows Community Toolkit is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows 10. | Target | Branch | Status | Recommended package version | @@ -16,23 +16,19 @@ All documentation for the toolkit is hosted on [Microsoft Docs](https://docs.mic ## Windows Community Toolkit Sample App :iphone: Want to see the toolkit in action before jumping into the code? Download and play with the [Windows Community Toolkit Sample App](https://www.microsoft.com/store/apps/9nblggh4tlcq) from the Store. +## Contribution :rocket: +Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page to learn more about contribution and guidelines. + ## NuGet Packages :package: NuGet is a standard package manager for .NET applications which is built into Visual Studio. From your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names mentioned in [Windows Community Toolkit Nuget Packages](https://docs.microsoft.com/en-us/windows/communitytoolkit/nuget-packages) table to search for it online. ## Features :mailbox: The [Features list](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md#controls) refers to all the currently available features that can be found in the Windows Community Toolkit. Most features should work with the October 2018 Update (1809) SDK 17763 and above; however, refer to specific documentation on each feature for more information. -## Required Dependencies :pushpin: -The following dependencies are required for building the Windows Community Toolkit repo and sample app: - -* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) with UWP and .NET workloads - * You'll also need to check the `C++ (v142) Universal Windows Platform tools` option under the UWP workload -* [Windows SDK April 2020 Update 19041](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive) -* [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/visual-studio-sdks) -* [.NET Framework 4.6.2 Developer Pack](https://dotnet.microsoft.com/download/visual-studio-sdks) - -## Contribution :rocket: -Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page to learn more about contribution and guidelines. +## Principles :ballot_box_with_check: +* Principle **#1**: The toolkit will be kept simple. +* Principle **#2**: As soon as a comparable feature is available in the Windows SDK for Windows 10, it will be marked as deprecated. +* Principle **#3**: All features will be supported for two Windows SDK for Windows 10 release cycles or until another principle supersedes it. ## Roadmap :earth_americas: Read what we [plan for next iterations](https://github.com/windows-toolkit/WindowsCommunityToolkit/milestones), and feel free to ask questions. From 989d7c06baf8f87a612be09ad21e5d9322c06a25 Mon Sep 17 00:00:00 2001 From: Kyaa Dost <35208324+Kyaa-dost@users.noreply.github.com> Date: Fri, 6 Nov 2020 11:35:10 -0800 Subject: [PATCH 16/18] Update readme.md --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 004ecd17d2f..6f19ce54bf5 100644 --- a/readme.md +++ b/readme.md @@ -20,7 +20,7 @@ Want to see the toolkit in action before jumping into the code? Download and pla Do you want to contribute? Check out our [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) page to learn more about contribution and guidelines. ## NuGet Packages :package: -NuGet is a standard package manager for .NET applications which is built into Visual Studio. From your open solution, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names mentioned in [Windows Community Toolkit Nuget Packages](https://docs.microsoft.com/en-us/windows/communitytoolkit/nuget-packages) table to search for it online. +NuGet is a standard package manager for .NET applications which is built into Visual Studio. When you open solution in Visual Studio, choose the *Tools* menu > *NuGet Package Manager* > *Manage NuGet packages for solution...* Enter one of the package names mentioned in [Windows Community Toolkit Nuget Packages](https://docs.microsoft.com/en-us/windows/communitytoolkit/nuget-packages) table to search for it online. ## Features :mailbox: The [Features list](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md#controls) refers to all the currently available features that can be found in the Windows Community Toolkit. Most features should work with the October 2018 Update (1809) SDK 17763 and above; however, refer to specific documentation on each feature for more information. From e5d0ecacd74578ab3d2cc12865fa1b19fca8ab0e Mon Sep 17 00:00:00 2001 From: "Michael Hawker MSFT (XAML Llama)" <24302614+michael-hawker@users.noreply.github.com> Date: Fri, 6 Nov 2020 13:14:46 -0800 Subject: [PATCH 17/18] Update readme.md --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 6f19ce54bf5..dc0bee486e6 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ The Windows Community Toolkit is a collection of helper functions, custom contro | Target | Branch | Status | Recommended package version | | ------ | ------ | ------ | ------ | | Production | rel/6.1.0 | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=rel/6.1.0)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10&branchName=rel/6.1.0) | [![NuGet](https://img.shields.io/nuget/v/Microsoft.Toolkit.Uwp.svg)](https://www.nuget.org/profiles/Microsoft.Toolkit) | -| Pre-release beta testing | master | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=master)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10) | [![MyGet](https://img.shields.io/dotnet.myget/uwpcommunitytoolkit/vpre/Microsoft.Toolkit.Uwp.svg)](https://dotnet.myget.org/gallery/uwpcommunitytoolkit) | +| Pre-release beta testing | master | [![Build Status](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_apis/build/status/Toolkit-CI?branchName=master)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_build/latest?definitionId=10) | [![DevOps](https://vsrm.dev.azure.com/dotnet/_apis/public/Release/badge/696bc9fd-f160-4e97-a1bd-7cbbb3b58f66/1/1)](https://dev.azure.com/dotnet/WindowsCommunityToolkit/_packaging?_a=feed&feed=WindowsCommunityToolkit-MainLatest) | ## Getting Started :raised_hands: Please read the [Getting Started with the Windows Community Toolkit](https://docs.microsoft.com/windows/communitytoolkit/getting-started) page for more detailed information about using the toolkit. From 987f57dec5bcad05e4717287d1fe8909174ef5c9 Mon Sep 17 00:00:00 2001 From: "Michael Hawker MSFT (XAML Llama)" <24302614+michael-hawker@users.noreply.github.com> Date: Fri, 6 Nov 2020 13:16:26 -0800 Subject: [PATCH 18/18] Update contributing.md --- contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index e84df22fa8d..d9c03e76af1 100644 --- a/contributing.md +++ b/contributing.md @@ -30,7 +30,7 @@ WCT has a list of issues that are labeled as [help wanted](https://github.com/wi Due to the involvement of multiple steps to add or improve documents; it is required to visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) and follow contribution guidelines. - ## Create, Submit or Review Pull Request :rocket: +## Create, Submit or Review Pull Request :rocket: Anyone with write access can create a Pull Request by forking the Windows Community Toolkit Repository. Here is how you can [Create a Pull Request from fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Once you fork the Windows Community Toolkit repo, it is essential to create all changes in the feature branch of your forked repository. If you have the changes in the forked feature branch, you can then create a Pull Request in the main Windows Community Toolkit. Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it requires to Submit or Review Pull Request.