Update CONTRIBUTING.md and Remove Duplicate Docs #10715

chiaramooney · 2025-08-08T19:15:16Z

Description

Update CONTRIBUTING.md to reflect current state of contributing to the WinUI repo.
Delete duplicate docs:

docs/contribution_workflow.md (content now included in CONTRIBUTING.md)
docs/SECURITY.md (content already contained in ./SECURITY.md)
src/*.md
src/LICENSE

Motivation and Context

Docs should be simplified, clear, and up-to-date.

How Has This Been Tested?

N/A

Screenshots (if appropriate):

N/A

michael-hawker · 2025-08-13T19:06:40Z

@codendone @azchohfi are the docs in the src folder coming from the repo sync? How should we handle those? In the internal repo can we just remove them since we have them in the root of this repo?

codendone · 2025-08-13T20:40:29Z

@michael-hawker Nope, these can simply be merged like normal.

codendone · 2025-08-13T21:39:44Z

@michael-hawker @chiaramooney Oops, correction, the src/ files are mirrored from the internal repo. I thought those were excluded from mirroring, but they aren't, so they'll be overwritten (or added back) on the next mirror. The root and docs/ files are fine.

chiaramooney · 2025-08-14T14:22:04Z

@codendone @michael-hawker Makes sense! I'll remove the src/ files from being deleted in this PR. Is there a good spot I could file an issue for removing those docs from the source being mirrored? Would that be on the GitHub repo or in ADO?

chrisglein · 2025-08-14T19:33:09Z

CONTRIBUTING.md

+1. Create an issue for your work. 
+    - You can skip this step for trivial changes or if there is an existing issue for the bug/feature.
+    - If your change adds or changes public APIs or UI, first follow the [New Feature or API Process](docs/feature_proposal_process.md).
+    - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.


I know this part is WIP, but I don't this guidance is up to date.

Suggested change

1. Create an issue for your work.

- You can skip this step for trivial changes or if there is an existing issue for the bug/feature.

- If your change adds or changes public APIs or UI, first follow the [New Feature or API Process](docs/feature_proposal_process.md).

- Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.

1. Have an issue tracking what you want to fix.

- If one doesn't already exist, open an issue. But before investing time on a contribution make sure the issue has been triaged and your fix has a chance of being merged.

- If your change adds or changes public APIs or UI, first follow the [New Feature or API Process](docs/feature_proposal_process.md).

- Comment on the issue to indicate your intent to work on it.

Yeah, there's a lot of old guidance scattered everywhere, so there's a few different steps in flight to try and get this up-to-date. Part of it too is whether we document how things work now, or more how we want things to work - and then move towards aligning to that as the OSS plan moves forward.

These steps were taken from the original https://github.com/microsoft/microsoft-ui-xaml/blob/main/docs/contribution_workflow.md. As of right now, there isn't a steady cadence of issues being triaged and the repo isn't ready for code contributions, so all of this guidance is speculative.

Would delete the entire section and add something later during Phase 3.

CONTRIBUTING.md

Co-authored-by: Chris Glein <[email protected]>

codendone · 2025-08-18T23:45:02Z

CONTRIBUTING.md

+- "`<`Resource`>` could be more inclusive and accessible if you considered `<`alternative`>` because `<`benefit`>`. Have you considered making these changes?"
+
+Many of the resources we provide are also open source themselves! It can sometimes be more effective to leave feedback on the more specific repo. This includes:
+- [documentation](https://github.com/MicrosoftDocs/windows-uwp)


windows-uwp

/windows-uwp appears to redirect to /windows-dev-docs. Should this directly specify the latter?

Sounds good; will change.

…y/microsoft-ui-xaml into user/chiara/fix-docs

riverar · 2025-08-24T22:29:49Z

CONTRIBUTING.md


-We welcome your input and contributions to all aspects of WinUI, including bug reports, doc updates, feature proposals, and API spec discussions.
+This document contains general guidance. More specific guidance is included in the documents linked below and within the repository’s [Wiki](https://github.com/microsoft/microsoft-ui-xaml/wiki) pages.


Looks like this was pasted from Word (see the smart apostrophes and quotes). May want to filter them out.

riverar · 2025-08-24T22:35:16Z

CONTRIBUTING.md

+1. Create an issue for your work. 
+    - You can skip this step for trivial changes or if there is an existing issue for the bug/feature.
+    - If your change adds or changes public APIs or UI, first follow the [New Feature or API Process](docs/feature_proposal_process.md).
+    - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.


Would delete the entire section and add something later during Phase 3.

riverar · 2025-08-24T22:36:45Z

CONTRIBUTING.md

+## Checks
+Each pull request to main must pass the following checks: [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21)


Community can't view this so I would delete it.

riverar · 2025-08-24T22:37:12Z

CONTRIBUTING.md


-## Documentation and usage samples
+The license/cla check confirms that you have completed the [CLA](https://cla.microsoft.com/).


CLA is an acronym.

Suggested change

The license/cla check confirms that you have completed the [CLA](https://cla.microsoft.com/).

The license/CLA check confirms that you have completed the [CLA](https://cla.microsoft.com/).

riverar · 2025-08-24T22:37:38Z

CONTRIBUTING.md


-Before new features are added to WinUI, we always perform a thorough API review and spec discussion. This can range from a single new API to an entire new control featuring dozens of new APIs. Joining such a spec discussion is a great opportunity for developers to help ensuring that new WinUI APIs will look and feel natural. In addition, spec discussions are the follow-up to feature proposals and will go into much finer details than the initial proposal. As such, taking part in these discussions gives developers the chance to be involved in the complete development process of new WinUI features - from their initial high-level inception right down to specific implementation/behavior details. These discussions take place in the WInUI repository, i.e. this repository.
+This pipeline extends [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) to validate more platforms, adding Debug and ARM. It is run after your changes are merged to main.


More unclickable links.

riverar · 2025-08-24T22:39:52Z

CONTRIBUTING.md

+Your feedback is most effective when it is a constructive call to action on the team, and is clear and detailed – especially on the "why" so that we can make sure whatever it is that we arrive at together appropriately focuses on your goal and your intended outcome from start to finish. 

-The WinUI team accepts code changes that improve WinUI or fix bugs, as long as they follow the processes outlined below and broadly align with our [roadmap](docs/roadmap.md).
+**Examples of constructively phrased feedback:**

-While we strive to accept all community contributions that meet the guidelines outlined here, please note that we may not merge changes that have narrowly-defined benefits due to compatibility risks and maintenance costs. We may also revert changes if they are found to be breaking.
+Instead of:

-### Code contribution process
+- The state of the platform is disappointing. I am not going to consider WinUI until my trust has been earned.

-For details see:
+Try this:
+- Deprecation of past frameworks has left me burned. The following would go a long way in earning my trust because my company is trying to launch an app next year and will need it supported for at least 5 more: 
+    - OSS
+    - High-confidence 5-year roadmap
+    - Guaranteed support timeline

-* [Setup and build environment](docs/developer_guide.md#Prerequisites)
-* [Source code structure](docs/source_code_structure.md)
-* [Contribution workflow](docs/contribution_workflow.md)
-* [Coding style and conventions](docs/code_style_and_conventions.md)
+This feedback provides clear actionable items that the WinUI team can take into consideration and address. 


We don't know what the team would consider a call to action and the example here is outdated and not something you want to encourage folks to submit. (I would delete all this text...) Consider changing the example at least to be more bug focused.

riverar · 2025-08-24T22:41:57Z

CONTRIBUTING.md

+1. Create a personal fork of the repository on GitHub (if you don't already have one).
+1. Create a branch off of main (git checkout -b mybranch). 
+    - Name the branch so that it clearly communicates your intentions (i.e. /user/janedoe/fix-datepicker).
+    - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
+1. Make and commit your changes. 
+    - Please follow our [Commit Messages](#commit-messages) guidance.
+1. Add new tests corresponding to your change, if applicable.
+1. Build the repository with your changes. 
+    - Make sure that the builds are clean.
+    - Make sure that the tests are all passing, including your new tests.
+1. Create a pull request (PR) against this repository's main branch. 
+    - Push your changes to your fork on GitHub (if you haven't already).
+    - Note: It is okay for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.


Markdown is designed to be readable when it's not rendered. Using 1. for all items makes it much more difficult to read outside a rendered view. I recognize this makes editing/authoring slightly harder but it'll increase readability (and align with standard practices) and compatibility with other renderers that may not implement this quirk.

microsoft-github-policy-service bot added the needs-triage Issue needs to be triaged by the area owners label Aug 8, 2025

beth-panx requested review from niels9001 and michael-hawker August 13, 2025 17:20

Update Docs

88bab8c

chiaramooney force-pushed the user/chiara/fix-docs branch from 891aa03 to 88bab8c Compare August 14, 2025 14:24

chiaramooney added 3 commits August 14, 2025 07:26

Remove Contribution Workflow

f266f6f

Add Contribution Feedback Section

ddd66a2

Refine

818c913

chrisglein reviewed Aug 14, 2025

View reviewed changes

beth-panx removed the needs-triage Issue needs to be triaged by the area owners label Aug 15, 2025

chiaramooney and others added 2 commits August 18, 2025 13:46

Remove Duplicates

b2161e6

Update CONTRIBUTING.md

370666d

Co-authored-by: Chris Glein <[email protected]>

codendone reviewed Aug 18, 2025

View reviewed changes

chiaramooney added 2 commits August 19, 2025 08:51

Update Link

8531731

Merge branch 'user/chiara/fix-docs' of https://github.com/chiaramoone…

20a1263

…y/microsoft-ui-xaml into user/chiara/fix-docs

riverar reviewed Aug 24, 2025

View reviewed changes


		We welcome your input and contributions to all aspects of WinUI, including bug reports, doc updates, feature proposals, and API spec discussions.
		This document contains general guidance. More specific guidance is included in the documents linked below and within the repository’s [Wiki](https://github.com/microsoft/microsoft-ui-xaml/wiki) pages.

		## Checks
		Each pull request to main must pass the following checks: [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21)


		## Documentation and usage samples
		The license/cla check confirms that you have completed the [CLA](https://cla.microsoft.com/).


		Before new features are added to WinUI, we always perform a thorough API review and spec discussion. This can range from a single new API to an entire new control featuring dozens of new APIs. Joining such a spec discussion is a great opportunity for developers to help ensuring that new WinUI APIs will look and feel natural. In addition, spec discussions are the follow-up to feature proposals and will go into much finer details than the initial proposal. As such, taking part in these discussions gives developers the chance to be involved in the complete development process of new WinUI features - from their initial high-level inception right down to specific implementation/behavior details. These discussions take place in the WInUI repository, i.e. this repository.
		This pipeline extends [WinUI-Public-MUX-PR](https://dev.azure.com/ms/microsoft-ui-xaml/_build?definitionId=21) to validate more platforms, adding Debug and ARM. It is run after your changes are merged to main.

Update CONTRIBUTING.md and Remove Duplicate Docs #10715

Are you sure you want to change the base?

Update CONTRIBUTING.md and Remove Duplicate Docs #10715

Uh oh!

Conversation

chiaramooney commented Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Uh oh!

michael-hawker commented Aug 13, 2025

Uh oh!

codendone commented Aug 13, 2025

Uh oh!

codendone commented Aug 13, 2025

Uh oh!

chiaramooney commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riverar Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chiaramooney commented Aug 8, 2025 •

edited

Loading

chiaramooney commented Aug 14, 2025 •

edited

Loading

riverar Aug 24, 2025 •

edited

Loading