Skip to content

Commit 85f50b1

Browse files
authored
Update contributing.md
1 parent ebe9787 commit 85f50b1

File tree

1 file changed

+6
-110
lines changed

1 file changed

+6
-110
lines changed

contributing.md

Lines changed: 6 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -28,18 +28,9 @@ Once you fork the Windows Community Toolkit repo, it is essential to create all
2828
: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:
2929

3030

31-
## <a name="submit-pr"></a>Submit Pull Request :rocket:
32-
Before submitting Pull Request, you must:
31+
## <a name="submit-pr"></a>Submit or Review Pull Request :rocket:
3332

34-
* Test your code with the [supported SDKs](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/readme.md#supported)
35-
* Follow the [quality guidance](#xaml), [coding style and conventions](#conventions), and [naming convention](#naming)
36-
* Target master branch (or an appropriate release branch if appropriate for a bug fix)
37-
* Follow the Windows Community Toolkit [PR Template](https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
38-
* If adding a new feature
39-
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.
40-
o Add or update a sample for the [Sample app](https://github.com/windows-toolkit/WindowsCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.SampleApp)
41-
 If creating a new sample, create a new icon by following the [Thumbnail Style Guide and templates](https://github.com/Microsoft/UWPCommunityToolkit-design-assets)
42-
o Add or update unit tests (if applicable)
33+
Please visit [Windows Community Toolkit Wiki](https://aka.ms/wct/wiki) for detailed information and steps it require to Submit or Review Pull Request.
4334

4435

4536
## <a name="pr"></a>Add New Feature :mailbox_with_mail:
@@ -48,106 +39,11 @@ o Add or update unit tests (if applicable)
4839
* If it gets approved by the team, proceed to submit a PR of the proposed Feature.
4940
* If the PR contains an error-free code and the reviewer signs off, the PR will be merged.
5041

51-
## <a name="docs"></a> Add Documentation :page_with_curl:
52-
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**.
42+
## <a name="docs"></a> Add or Improve Documentation :page_with_curl:
5343

54-
Make sure to update both Pull Requests with a link to each other.
44+
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.
5545

56-
If adding a new documentation page:
57-
58-
* Copy the [documentation template](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/.template.md) and follow the same format.
59-
60-
* Update the [Table of Contents](https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/blob/master/docs/toc.md) to point to the new page
61-
62-
## <a name="improve-docs"></a> Improve Documentation :page_with_curl:
63-
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:
64-
65-
For documentation regarding introducing new features, please base your fork off the master branch.
66-
67-
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.
68-
69-
Once the PR is submitted and merged then depending on the improvement you are proposing the changes will eventually appear in these links.
70-
71-
- [Staging review from 'master' branch](https://review.docs.microsoft.com/windows/communitytoolkit/?branch=master) **This link is currently only available for Microsoft Employees**
72-
- [Live site from 'live' branch](https://docs.microsoft.com/windows/communitytoolkit)
73-
74-
## Review PR :book:
75-
76-
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)
77-
78-
Steps to review PR
79-
80-
* Open Command Prompt or [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab)
81-
* Locate the place where you want the WCT clone to appear by using the cd path.
82-
* Go to [Windows Community Toolkit](https://github.com/windows-toolkit/WindowsCommunityToolkit) repository and click on **Code** button to copy the HTTPS or SSH URL.
83-
* Paste the link in Command Prompt by following the [Hub Command](https://hub.github.com/#developer) to Clone Windows Community Toolkit.
84-
* [Fork](https://hub.github.com/#contributor) the repo by following the command.
85-
* Checkout PR by using [hub pr checkout](https://hub.github.com/hub-pr.1.html#synopsis) Command
86-
* Open the Visual Studio
87-
* Click on “Open a project or solution”
88-
* Locate the cloned repository folder in the local machine and select the .sln file to open the solution.
89-
* 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).
90-
* 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.
91-
* Review and test the changes side by side.
92-
* Once approved signoff by leaving feedback and results.
9346

9447

95-
## <a name="xaml"></a> Building XAML Controls :control_knobs:
96-
Follow these guidelines when submitting Pull Requests for controls:
97-
98-
* Your control must be usable and efficient with the keyboard only.
99-
* Tab order must be logical.
100-
* Focused controls must be visible.
101-
* Action must be triggered when hitting the Enter key.
102-
* Do not use custom colors but instead rely on theme colors so high contrasts themes can be used with your control.
103-
* 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).
104-
* Don't use the same Name on two different elements unless they have different control types.
105-
* 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.
106-
* 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).
107-
108-
## <a name="conventions"></a> Coding Style and Conventions :balance_scale:
109-
* DO NOT require that users perform any extensive initialization before they can start programming basic scenarios.
110-
* DO provide good defaults for all values associated with parameters, options, etc.
111-
* DO ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation.
112-
* DO communicate incorrect usage of APIs as soon as possible.
113-
* DO design an API by writing code samples for the main scenarios. Only then, you define the object model that supports those code samples.
114-
* DO NOT use regions. DO use partial classes instead.
115-
* DO declare static dependency properties at the top of their file.
116-
* DO NOT seal controls.
117-
* DO use extension methods over static methods where possible.
118-
* DO NOT return true or false to give success status. Throw exceptions if there was a failure.
119-
* DO use verbs like GET.
120-
* DO NOT use verbs that are not already used like fetch.
121-
122-
## <a name="accessibility"></a> Accessibility Guideline
123-
124-
Basic accessibility features for each control.
125-
126-
### Color & High Contrast themes
127-
* Controls must support the 4 high contrast themes by default on Windows, in addition to changing the theme while the app is running.
128-
* Controls must have a contrast ratio of at least 4.5:1 between the text (and images with text) and the background behind it.
129-
### Keyboard
130-
* 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.
131-
* Composite elements must ensure proper inner navigation among the contained elements
132-
* Clickable UI elements must be invokable with the keyboard (The trigger keys are enter and space).
133-
* Focusable elements must have a visual focus indicator. It's usually a rectangle shape around the control's normal bounding rectangle.
134-
### Narrator
135-
* Controls must support the narrator.
136-
137-
## <a name="naming"></a> Naming conventions
138-
* We are following the coding guidelines of [.NET Core Foundational libraries](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md).
139-
140-
## <a name="documentation"></a> Documentation
141-
* DO NOT expect that your API is so well designed that it needs no documentation. No API is that intuitive.
142-
* DO provide great documentation with all APIs.
143-
* DO use readable and self-documenting identifier names.
144-
* DO use consistent naming and terminology.
145-
* DO provide strongly typed APIs.
146-
* DO use verbose identifier names.
147-
148-
## <a name="files"></a> Files and folders
149-
* DO associate no more than one class per file.
150-
* DO use folders to group classes based on features.
151-
152-
153-
: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:
48+
# Thank You :heart::heart:
49+
**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.**

0 commit comments

Comments
 (0)