From c67c5aa6189c0dc0894cbfc6704777bee5a9a011 Mon Sep 17 00:00:00 2001 From: Dan McLachlan Date: Sun, 7 Sep 2014 21:28:05 -0700 Subject: [PATCH] Updated README.md and CONTRIBUTING.md - Renamed CONTRIBUTING to CONTRIBUTING.md - Moved directory structure info from README.md to CONTRIBUTING.md - Updated contribution process - CLA submission process now automated via the Azure pull request bot - Detailed the contribution process including How-To for verifying changes --- CONTRIBUTING | 175 ------------------------------------------------ CONTRIBUTING.md | 155 ++++++++++++++++++++++++++++++++++++++++++ README.md | 44 +----------- 3 files changed, 157 insertions(+), 217 deletions(-) delete mode 100644 CONTRIBUTING create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING b/CONTRIBUTING deleted file mode 100644 index 6389bc67..00000000 --- a/CONTRIBUTING +++ /dev/null @@ -1,175 +0,0 @@ - Contribution License Agreement - -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. - -_______________________________________________________________________________ - -This Contribution License Agreement ("Agreement") is agreed to by the parties -signing below ("You"), and conveys certain license rights to Microsoft -Corporation and its affiliates ("Microsoft") for Your contributions to Microsoft -open source projects. This Agreement is effective as of the latest signature -date below ("Effective Date"). - -1. Definitions. - -"Code" means the computer software code, whether in human-readable or -machine-executable form, that is delivered by You to Microsoft under this -Agreement. - -"Project" means any of the projects owned or managed by Microsoft and offered -under a license approved by the Open Source Initiative (www.opensource.org). - -"Submit" is the act of uploading, submitting, transmitting, or distributing code -or other content to any Project, including but not limited to communication on -electronic mailing lists, source code control systems, and issue tracking -systems that are managed by, or on behalf of, the Project for the purpose of -discussing and improving that Project, but excluding communication that is -conspicuously marked or otherwise designated in writing by You as -"Not a Submission." - -"Submission" means the Code and any other copyrightable material Submitted by -You, including any associated comments and documentation. - -2. Your Submission. You must agree to the terms of this Agreement before making -a Submission to any Project. This Agreement covers any and all Submissions that -You, now or in the future (except as described in Section 4 below), Submit to -any Project. - -3. Originality of Work. You represent that each of Your Submissions is entirely -Your original work. Should You wish to Submit materials that are not Your -original work, You may Submit them separately to the Project if You (a) retain -all copyright and license information that was in the materials as you received -them, (b) in the description accompanying your Submission, include the phrase -"Submission containing materials of a third party:" followed by the names of the -third party and any licenses or other restrictions of which You are aware, and -(c) follow any other instructions in the Project's written guidelines concerning -Submissions. - -4. Your Employer. If You have an employer (other than yourself), You must have -the employer sign in one of the two spaces indicated below. If the employer -signs in the first space, the term "You" in this Agreement will refer to You and -the employer collectively. If You change employers in the future and desire to -Submit additional Submissions, then You agree to sign a new Agreement signed by -the new employer before Submitting those Submissions. - -5. Licenses. - - a. Copyright License. You grant Microsoft, and those who receive the Code - directly or indirectly from Microsoft, a perpetual, worldwide, - non-exclusive, royalty-free, irrevocable license in the Submission to - reproduce, prepare derivative works of, publicly display, publicly perform, - and distribute the Submission and such derivative works, and to sublicense - any or all of the foregoing rights to third parties. - - b. Patent License. You grant Microsoft, and those who receive the Code - directly or indirectly from Microsoft, a perpetual, worldwide, - non-exclusive, royalty-free, irrevocable license under your patent claims - that directly read on the Code to make, have made, use, offer to sell, sell - and import or otherwise dispose of the Code. - - c. Other Rights Reserved. Each party reserves all rights not expressly - granted in this Agreement. No additional licenses or rights whatsoever - (including, without limitation, any implied licenses) are granted by - implication, exhaustion, estoppel or otherwise. - -6. Representations and Warranties. You represent that You are legally entitled -to grant the above licenses. You represent that each of Your Submissions is -entirely Your original work (except as you may have disclosed under Section 3). -If an individual is signing this Agreement on behalf of the employer of a person -making a Submission, pursuant to Section 4 above, the individual represents and -warrants that he or she has the necessary authority to bind the listed employer -to the obligations contained in this Agreement. You are not expected to provide -support for Your Submission, unless you choose to do so. UNLESS REQUIRED BY -APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES EXPRESSLY -STATED IN SECTIONS 3, 4, AND 6, THE SUBMISSION PROVIDED UNDER THIS AGREEMENT IS -PROVIDED WITHOUT WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY -WARRANTY OF NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR -PURPOSE. - -7. Notice to Microsoft. You agree to notify Microsoft in writing of any facts or -circumstances of which You later become aware that would make Your -representations in this Agreement inaccurate in any respect. - -8. Information about Submissions. You acknowledge that contributions to Projects -and information about contributions may be maintained indefinitely and disclosed -publicly, including your name and other information that you submit with Your -Submission. - -9. Governing Law/Jurisdiction/Attorneys' Fees. This Agreement shall be construed -and controlled by the laws of the State of Washington, and the parties consent -to exclusive jurisdiction and venue in the federal courts sitting in King -County, Washington, unless no federal subject matter jurisdiction exists, in -which case the parties consent to exclusive jurisdiction and venue in the -Superior Court of King County, Washington. The parties waive all defenses of -lack of personal jurisdiction and forum non-conveniens. Process may be served on -either party in the manner authorized by applicable law or court rule. In any -action to enforce any right or remedy under this Agreement or to interpret any -provision of this Agreement, the prevailing party shall be entitled to recover -its reasonable attorneys' fees, costs and other expenses. - -10. Entire Agreement/Assignment. This Agreement is the entire agreement between -the parties, and supersedes any and all prior agreements, understandings or -communications, written or oral, between the parties relating to the subject -matter hereof. This Agreement may be assigned by Microsoft. - - -Name ("You"): -___________________________________________________________ - -Signature: -___________________________________________________________ - -Date: -___________________________________________________________ - -Primary email address: -___________________________________________________________ - -Mailing address: -___________________________________________________________ - -In addition to Your signature above, please initial one of the boxes below: - -___ I am employed by someone else, and per Section 4 above, my employer, -by signing below, agrees to be a party to this Agreement, and the defined term -"You" includes my employer. - - Employer Name (Individual or Company): ____________________________________ - Signature: _________________________________________ - By: _________________________________________ - Title: _________________________________________ - Date: _________________________________________ - -___ I am employed by someone else, and my employer, by signing below, waives -any rights it may have to my Submissions by virtue of my having created it -during the term of my employment (including by virtue of any contract with my -employer). If signed below, the defined term "You" does not include my -employer. - - Employer Name (Individual or Company): ____________________________________ - Signature: _________________________________________ - By: _________________________________________ - Title: _________________________________________ - Date: _________________________________________ - -___ I am not employed by anyone (other than myself) and have sole rights to my -Submissions. - -If you have multiple employers, please attach a signature page for each of the -employers. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ef9e3ae2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,155 @@ +# Contribute to the Win2D Project + +Thank you for your interest in the Win2D project! + +* [Before we can accept your pull request](#before-we-can-accept-your-pull-request) +* [Source Directory Structure](#source-directory-structure) +* [Contribute](#contribute) + +## Before we can accept your pull request + +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](#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 +[win2dcla@microsoft.com](mailto:win2dcla@microsoft.com) and we will send you the +form to sign, scan and return. + +## Source Directory Structure + +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 + +**/numerics** - Cross-platform vector and matrix math library. There are three implementations: +- /Cpp +- /DotNet +- /WinRT + +**/obj** - Intermediate files generated by the build + +**/samples** - Example projects showing how to use Win2D + +**/tests** - Test projects that consume Win2D in a similar way to how an +external customer would. Each one is a Windows Store app. These tests are run for manual +verification. + +**/tools** - Standalone utilities, separate from Win2D product code +- /codegen - Generates headers+IDL from XML resource files (you don't have to build this to build Win2D) +- /copyright - Verifies the right copyright banner appears at the top of each source file +- /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! + - /WinRTDirectX - projections for D3D/DXGI types +- /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 + +## Contribute + +In order for the contribution process to be as seamless as possible, the +following procedure has been established. + +1. Create a new branch +2. Add new content or edit existing content +3. Verify your changes +4. Submit a pull request to the main repository +5. 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. + +#### Create a new branch + +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' + +#### Add new content or edit existing content + +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. + +#### Verify your changes + +If you have added new functionality please make sure to add tests to the +appropriate test suites. + +To validate your changes, run "msbuild /m Win2D.proj" from a Visual Studio +command prompt. This will: + +- Build all flavors of all projects (debug, release, x86, x64, and ARM) +- Run all automated tests +- Generate updated reference documentation +- Make sure all source files include the correct Apache copyright header + +The documentation generation step requires you to have installed the +Sandcastle tools from https://shfb.codeplex.com. + +To run Store unit tests, you must have a Windows Store development license +installed on your computer, and must install a test package certificate as +described in the Remarks section of http://msdn.microsoft.com/en-us/library/windows/desktop/jj835836%28v=vs.85%29.aspx + +#### Submit a pull request to the main repository + +When you are done with your work and are ready to have it merged into the central +repository follow these steps. + +1. Push your branch back to GitHub +2. On the GitHub site, navigate in your fork to the new branch +3. Click the **Pull Request** button at the top of the page +4. Ensure that the Base branch is 'Win2D@master' and the Head branch is +'/Win2D@' +5. Click the **Update Commit Range** button +6. 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. +7. 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. + +#### Delete a branch + +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. \ No newline at end of file diff --git a/README.md b/README.md index e68d63e3..4d4f4dd1 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ in an early, incomplete state is to solicit early developer feedback. - [Documentation](http://microsoft.github.io/Win2D) - [Team blog](http://blogs.msdn.com/b/win2d) - [License](http://www.apache.org/licenses/LICENSE-2.0.html) -- [Contributing](http://github.com/Microsoft/Win2D/blob/master/CONTRIBUTING) +- [Contributing](http://github.com/Microsoft/Win2D/blob/master/CONTRIBUTING.md) ## Code Example To give you a flavor of what the code looks like, here is a snippet of XAML: @@ -74,44 +74,4 @@ Follow the steps below to get started on writing your own apps. - Change Solution platform from 'Any CPU' to x86 - You are now ready to hit F5 (Build) -A working sample can be found in the Samples directory. - -## Source Directory Structure - -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 - -**/numerics** - Cross-platform vector and matrix math library. There are three implementations: -- /Cpp -- /DotNet -- /WinRT - -**/obj** - Intermediate files generated by the build - -**/samples** - Example projects showing how to use Win2D - -**/tests** - Test projects that consume Win2D in a similar way to how an -external customer would. Each one is a Windows Store app. These tests are run for manual -verification. - -**/tools** - Standalone utilities, separate from Win2D product code -- /codegen - Generates headers+IDL from XML resource files (you don't have to build this to build Win2D) -- /copyright - Verifies the right copyright banner appears at the top of each source file -- /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! - - /WinRTDirectX - projections for D3D/DXGI types -- /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 +A working sample can be found in the Samples directory. \ No newline at end of file