Thank you for your interest in the Win2D project!
Microsoft asks that all contributors sign a contributor license agreement (CLA). CLAs are generally common and accepted in most open source software projects. We all want Microsoft's open source projects to be as widely used and distributed as possible. We also want its users to be confident about the origins and continuing existence of the code. The CLA helps us achieve that goal by ensuring that we have the agreement of our contributors to use their work, whether it be code, or documentation.
The CLA permits Microsoft to distribute your code without restriction. It doesn't require you to assign to us any copyright you have, the ownership of the copyright remains with you. You cannot withdraw permission for use of the contribution at a later date.
We are generally seeking originally authored code and documentation as contributions. Should you wish to submit materials that are not your original work, you may submit them separately to the Project in accordance with the terms of the CLA.
Our Azure Pull Request Bot will automatically check for a signed CLA when you submit a pull request as described below in Contribute.
If there isn't a CLA on file, it will walk you through an all electronic process. Note: your employer may also have to complete an on-line form.
If you would rather use an off-line process, email [email protected] and we will send you the form to sign, scan and return.
Note: For the bulk of interesting product code, go to /winrt/lib.
/bin - Binary files generated by the build
/build - Shared, build-related resources that are common across projects
- /Assets - Common Windows Store assets used for tests and samples
- /nuget - Resources needed for building the NuGet package
/obj - Intermediate files generated by the build
/samples - Example projects showing how to use Win2D
/tools - Standalone utilities, separate from Win2D product code
- /checkcode - Verifies the right copyright banner appears at the top of each source file
- /codegen - Generates headers+IDL from XML resource files (you don't have to build this to build Win2D)
- /docs - Tools and scripts for building API reference documentation
/winrt - Win2D product code and automated tests
- /dll - Build resources for the product dll
- /docsrc - Source files used to create the reference documentation
- /inc - Common includes
- /lib - All the projected IDL and runtime class implementations
- /published - Headers that are included directly in the NuGet package for 3rd part consumption
- /test.external - Automated tests that use only the public WinRT interface
- /test.internal - Automated tests that link directly with winrt.lib to access internals of the implementation
- /test.managed - Automated tests written in C#
- /test.nativecomponent - C++/CX component that exposes native functionality for use by test.managed
In order for the contribution process to be as seamless as possible, the following procedure has been established.
- Create a new branch
- Add new content or edit existing content
- Verify your changes
- Submit a pull request to the main repository
- Delete the branch
Each branch should be limited to a single feature/bug fix both to streamline work flow and reduce the possibility of merge conflicts.
This can be done in Visual Studio:
- Go to 'View' -> 'Team Explorer' -> 'Branches'
- Click 'New Branch'
- Enter the name of your new branch
- Check the check box 'Checkout branch'
- Click 'Create Branch'
Using Visual Studio or your favorite editor, add your new content or edit existing files.
You can commit multiple times while you are doing your work, or you can wait and commit only once when you're done.
If you have added new functionality please make sure to add tests to the appropriate test suites.
To validate your changes, run "msbuild /m /nr:false Win2D.proj" from a Visual Studio Developer Command Prompt. This will:
- Build all flavors of all projects (debug, release, x86, x64, ARM, and ARM64)
- Run all automated tests
- Generate updated reference documentation
- Make sure all source files include the correct MIT copyright header
To run Store unit tests, you must have the test package certificate and test signing key build\Assets\TemporaryKey.pfx in your Win2D repository.
You only need to perform the below steps once:
- Open a PowerShell command prompt.
- Using the PowerShell command prompt, change to the 'build' directory from the root of the repository.
- Run
powershell -ep Bypass GenerateTestPfx.ps1.- GenerateTestPfx.ps1 registers the test package certificate to CurrentUser\My certificate store and saves the private key to
build\Assets\TemporaryKey.pfxfor use in building the Store unit tests package. This file is ignored by .gitignore from being included in commits.
- GenerateTestPfx.ps1 registers the test package certificate to CurrentUser\My certificate store and saves the private key to
When you are done with your work and are ready to have it merged into the central repository follow these steps.
- Push your branch back to GitHub
- On the GitHub site, navigate in your fork to the new branch
- Click the Pull Request button at the top of the page
- Ensure that the Base branch is 'Win2D@master' and the Head branch is
<your username>/Win2D@<branch name> - Click the Update Commit Range button
- Give your pull request a Title, and describe all the changes being made. If your change fixes a GitHub issue make sure to reference it in the description.
- Submit the Pull Request
One of the site administrators will now process your pull request. Your pull request will surface on the Win2D site under Issues. When the Pull Request is accepted, the issue will be resolved.
Once your changes have been successfully merged into the central repository you can delete the branch you used, as you will no longer need it. Any further work requires a new branch.
Congratulations, you have successfully contributed to the project.