diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 187de0649a..8a4fec86f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,9 @@ We mark the most straightforward issues with labels. These issues are the place * [good first issues](https://github.com/Microsoft/microsoft-ui-xaml/labels/good%20first%20issue) * [help wanted](https://github.com/Microsoft/microsoft-ui-xaml/labels/help%20wanted) +Another great way to help is by voting and commenting on feature proposals: +* [feature request](https://github.com/Microsoft/microsoft-ui-xaml/labels/feature%20request) + ## Code contribution guidelines ### Proposing new public APIs or UI diff --git a/docs/contribution_workflow.md b/docs/contribution_workflow.md index 31554818d2..f943c1bb63 100644 --- a/docs/contribution_workflow.md +++ b/docs/contribution_workflow.md @@ -28,10 +28,10 @@ have one). 4. Make and commit your changes. * Please follow our [Commit Messages](contribution_workflow.md#Commit%20Messages) guidance. -5. Add new tests corresponding to your change, if applicable. +5. Add [new tests](developer_guide.md#Testing) corresponding to your change, if applicable. 6. 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. + * Make sure that the [tests](developer_guide.md#Testing) are all passing, including your new tests. 7. Create a pull request (PR) against the upstream repository's master 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 @@ -39,8 +39,8 @@ have one). or some appropriately small number of commits before your PR is merged. - Note: It is okay to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the - feedback process while you're still working on the implementation. State that this is - the case in the initial PR comment. + feedback process while you're still working on the implementation. State + that this is the case in the initial PR comment. ## DOs and DON'Ts @@ -65,8 +65,37 @@ fit to add to WinUI, file an issue and start a discussion before proceeding. * **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it. -* **DON'T** add or change public API or UI without filing an issue and discussing with us -first: see the [New Feature or API Process](feature_proposal_process.md). +* **DON'T** add or change public API or UI without filing an issue and +discussing it first: see the [New Feature or API Process](feature_proposal_process.md). + +## Checks + +Each pull request must pass the following checks. + +#### WinUI_build_OS + +This check essentially makes sure that your change actually builds. + +One snag you might hit is a failure in `PeformDEPControlsPort.cmd`. This +process validates the compatibility of your change with the port to the Windows +build system and [Windows.UI.Xaml.Controls](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls). +Unfortunately this process cannot be run locally without authentication to the +Windows build, so if you run into a problem with this validation step you may +need the help of a Microsoft employee. You may be able to look at similar code +and its use of `BUILD_WINDOWS` to figure out what you need to do, but feel free +to @ mention Microsoft team members to ask for help. + +#### WinUI-Public-MUX-PR + +> Note: Until [this issue](https://github.com/Microsoft/microsoft-ui-xaml/issues/49) +is resolved the only check made is build validation, not automated tests. + +This check runs automated tests on your change. These tests should match what +you're able to run with local automated testing using Test Explorer. + +#### license/cla + +This check confirms that you have completed the [CLA](https://cla.microsoft.com). ## Commit Messages diff --git a/docs/developer_guide.md b/docs/developer_guide.md index 0946038b92..38db83a7ac 100644 --- a/docs/developer_guide.md +++ b/docs/developer_guide.md @@ -7,14 +7,22 @@ improvements. #### /build, /tools -These folders contain scripts and other support machinery that you shouldn't need to edit for most changes. +These folders contain scripts and other support machinery that you shouldn't +need to edit for most changes. In particular: * **/build/NuSpecs** enables .nupkg generation * **/build/FrameworkPackage** enables .appx generation -Note that here and in various parts of the codebase you will see references to `BUILD_WINDOWS`. WinUI operates as a standalone package for Xaml apps but is also a way that new controls migrate into [Windows.UI.Xaml.Controls](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls) as part of the Windows build system. The places where the WinUI source needs to differ for this different environment are specified under `BUILD_WINDOWS`. It's expected that it is the responsibility of the Microsoft team members to maintain this part of WinUI, and other community members should be able to ignore it. +Note that here and in various parts of the codebase you will see references to +`BUILD_WINDOWS`. WinUI operates as a standalone package for Xaml apps but is +also a way that new controls migrate into [Windows.UI.Xaml.Controls](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls) +as part of the Windows build system. The places where the WinUI source needs to +differ for this different environment are specified under `BUILD_WINDOWS`. It's +expected that it is the responsibility of the Microsoft team members to +maintain this part of WinUI, and other community members should be able to +ignore it. #### /dev @@ -33,8 +41,8 @@ that contains all the controls and other solutions which will be packaged and deployed. At this time we believe the Microsoft.UI.Xaml.dll is small enough to include all controls into one DLL. As we increase the number of controls we will revisit this decision and may decompose it into different DLLs -in the future. Also we will adjust based on developer feedback if we start to see - usage patterns where teams use just a few controls vs. the whole library. +in the future. Also we will adjust based on developer feedback if we start to see +usage patterns where teams use just a few controls vs. the whole library. This project also includes the necessary definitions to package the DLL into a NuGet package. @@ -50,12 +58,15 @@ Note that developer usage documentation can be found separately on docs.microsof Our test library and test app (the app that the test library interacts with when executing the tests) are here. -MUXControls.Test is a [MSTest](https://docs.microsoft.com/dotnet/api/microsoft.visualstudio.testtools.unittesting) DLL using MITALite that contains all of the test -code for the various controls by automating the MUXControlsTestApp. +MUXControls.Test is a [MSTest](https://docs.microsoft.com/dotnet/api/microsoft.visualstudio.testtools.unittesting) +DLL using MITALite that contains all of the test code for the various controls +by automating the MUXControlsTestApp. MUXControlsTestApp is a UWP app that exercises all the controls. This is just a manual testing playground which can be driven by the automated tests for -automated verification as well as [TestMethod] control API verification. Note this applications references the MUXControls DLL rather than including the Shared Items. +automated verification as well as [TestMethod] control API verification. Note +this applications references the MUXControls DLL rather than including the +Shared Items. ## Code style and conventions @@ -86,7 +97,8 @@ The following file header is the used for WinUI. Please use it for new files. ## Building the repository -Generally you will want to set your configuration to **Debug**, **x86**, and select **MUXControlsTestApp** as your startup project in Visual Studio. +Generally you will want to set your configuration to **Debug**, **x86**, and +select **MUXControlsTestApp** as your startup project in Visual Studio. ### Prerequisites #### Visual Studio @@ -95,7 +107,11 @@ Install latest VS2017 (15.9 or later) from here: http://visualstudio.com/downloa #### SDK -While WinUI is designed to work against many versions of Windows, you will need a fairly recent SDK in order to build WinUI. It's required that you install the 16299, 17134 and 17763 SDKs. +While WinUI is designed to work against many versions of Windows, you will need +a fairly recent SDK in order to build WinUI. It's required that you install the +16299, 17134 and 17763 SDKs. You can download these via Visual Studio (check +all the boxes when prompted), or you can manually download them from here: +https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk ### Creating a NuGet package @@ -111,7 +127,10 @@ While WinUI is designed to work against many versions of Windows, you will need #### Test app -The WinUI solution project has a test app that is useful for validating common scenarios affected by the presence of the WinUI package. Set **MUXControlsTestApp** as your startup project in Visual Studio and you can F5 to start debugging that app and validate your changes. +The WinUI solution project has a test app that is useful for validating common +scenarios affected by the presence of the WinUI package. Set +**MUXControlsTestApp** as your startup project in Visual Studio and you can F5 +to start debugging that app and validate your changes. ##### Organization @@ -158,25 +177,55 @@ build and run MUXControl.ReleaseTest. One of the core values of WinUI is the way that it brings controls to a wide variety of versions of Windows, handling version compatibility differences so that developers using WinUI don't have to. As such, testing WinUI changes on -different versions is sometimes necessary. To accomplish this you will need to at times set up older versions of Windows for testing. To get these earlier versions you can make use of a Visual Studio subscription [as described here](https://docs.microsoft.com/azure/virtual-machines/windows/client-images). +different versions is sometimes necessary. To accomplish this you will need to +at times set up older versions of Windows for testing. To get these earlier +versions you can make use of a Visual Studio subscription [as described here](https://docs.microsoft.com/azure/virtual-machines/windows/client-images). ### Automated testing -> More information will be coming on this soon +You can run the test suite from within Visual Studio by using the Test top +level menu. For targeting indivual tests you can use [Test Explorer](https://docs.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer?view=vs-2017) +(found under the Test->Windows sub menu). + +This same suite of tests will be run as part of your Pull Request validation +[check](contribution_workflow.md#Checks). + +#### Creating a new test + +For your test to be discovered it needs to be a method tagged as [\[TestMethod\]](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.testtools.unittesting.testmethodattribute?view=mstest-net-1.2.0) +on a class tagged with as [\[TestClass\]](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.testtools.unittesting.testclassattribute?view=mstest-net-1.2.0). +With that metadata in place your new test method will be picked up by Test +Explorer. + +There are two types of tests you can use to validate your scenarios: +* **API Tests**: Run in the context of an app and validate the behaviors of our +APIs. +* **Interaction Tests**: Drive the UI on an external app and validate the +results using UI Automation. + +Keep in mind that your test will be executed on many different versions of +Windows, not just the most recent version. Your tests may need version or +[IsApiPresent](https://docs.microsoft.com/en-us/uwp/api/windows.foundation.metadata.apiinformation.istypepresent) +checks in order to pass on all versions. ## Telemetry -This project collects usage data and sends it to Microsoft to help improve our products and services. +This project collects usage data and sends it to Microsoft to help improve our +products and services. -If desired you can disable logging when building the project by following these steps: +If desired you can disable logging when building the project by following these +steps: -1. In Microsoft Visual Studio's Solution Explorer window, right-click the "Microsoft.UI.Xaml (Universal Windows)" project. +1. In Microsoft Visual Studio's Solution Explorer window, right-click the +"Microsoft.UI.Xaml (Universal Windows)" project. 2. Select the "Properties" menu. 3. Select "All Configurations" in the Configuration dropdown. 4. Select "All Platforms" in the Platform dropdown. -5. Select "Configuration Properties", then "C/C++", then "Preprocessor" in the left tree structure. +5. Select "Configuration Properties", then "C/C++", then "Preprocessor" in the +left tree structure. 6. In the entry called "Preprocessor Definitions": - * Add "DISABLE_TELEMETRY_TRACELOGGING;" to disable Microsoft telemetry logging alone. + * Add "DISABLE_TELEMETRY_TRACELOGGING;" to disable Microsoft telemetry + logging alone. * Add "DISABLE_PERF_TRACELOGGING;" to disable performance logging alone. * Add "DISABLE_DEBUG_TRACELOGGING;" to disable debug logging alone. * Or simply add "DISABLE_ALL_TRACELOGGING;" to disable all three types of logging. diff --git a/docs/roadmap.md b/docs/roadmap.md index 900501a3a9..121496bda6 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -8,7 +8,8 @@ For 2018-2019 the WinUI team is focused on: 1. Establishing our open source development process on GitHub -2. Continuing to extend the [Fluent Design System](https://www.microsoft.com/design/fluent) for Windows apps +2. Continuing to extend the [Fluent Design System](https://www.microsoft.com/design/fluent) +for Windows apps 3. Continuing to migrate UWP Xaml platform controls to WinUI @@ -20,12 +21,14 @@ For 2018-2019 the WinUI team is focused on: * a new Tip control * a new Ribbon control -We also welcome your code contributions, particularly if they fix bugs or add functionality that aligns with the above. +We also welcome your code contributions, particularly if they fix bugs or add +functionality that aligns with the above. See the [contribution guide](../CONTRIBUTING.md) for more info on contributing. ## NuGet releases -WinUI is distributed as official Microsoft [NuGet packages](https://docs.microsoft.com/nuget/what-is-nuget) which are regularly built from this repo. +WinUI is distributed as official Microsoft [NuGet packages](https://docs.microsoft.com/nuget/what-is-nuget) +which are regularly built from this repo. New **prerelease** NuGet packages are released approximately monthly. New **stable** NuGet packages are released approximately twice a year. @@ -33,4 +36,4 @@ New **stable** NuGet packages are released approximately twice a year. The list of WinUI packages can be found here: https://www.nuget.org/profiles/winui -The next stable release scheduled for the first half of 2019 will be WinUI 2.1. \ No newline at end of file +The next stable release scheduled for the first half of 2019 will be WinUI 2.1.