diff --git a/contributing.md b/contributing.md index b18bcaab6c9..d9c03e76af1 100644 --- a/contributing.md +++ b/contributing.md @@ -1,117 +1,39 @@ -# Contributing to the Windows Community Toolkit +# Contributing to the Windows Community Toolkit :sparkles::sparkles: -The foundation of the **Windows Community Toolkit** is simplicity. +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! -A developer should be able to quickly and easily learn to use the API. +In the next few steps, you will be able to see a glimpse of ways you can contribute to the Windows Community Toolkit. -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. +: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: -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. +## 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. -That's why many of the guidelines of this document are obvious and serve only one purpose: Simplicity. +For missing documentation related question, please file an issue at [Microsoft Docs](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new). - - [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) +## 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 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. -## 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` +## 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. -## 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. +## 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. -## Submitting a pull request -For every contribution, you must: +## Add or Improve Documentation :page_with_curl: -* 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) +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. -* 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) +## 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. -PR has to be validated by at least two core members before being merged. +Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it requires to Submit or Review Pull Request. -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. - -### Adding Documentation - -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 [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.** - -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) - -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 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 - -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. +# 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** diff --git a/readme.md b/readme.md index 8648a6e5700..dc0bee486e6 100644 --- a/readme.md +++ b/readme.md @@ -1,86 +1,44 @@ ---- -topic: sample -languages: -- csharp -products: -- windows ---- -# Windows Community Toolkit +# 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. -## Build Status | 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 -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 :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 -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. +## 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. -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 :package: +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. -![nuget packages](githubresources/images/NugetPackages.png "Nuget Packages") - -| 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 | - -## 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 -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) - -## Contributing -Do you want to contribute? Here are our [contribution guidelines](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/contributing.md). - -## 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. -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 +## 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).