Ajax Control Toolkit Patch Utility

Getting Started Guide

Do you want to be able to contribute fixes to the AJAX Control Toolkit, but you aren’t a contributor? The Patch Utility is an easy way to create fixes that can be submitted to the AJAX Control Toolkit team for evaluation and possible inclusion into the AJAX Control Toolkit.

Overview

Who would want to use this tool?
Anybody who does not have contributor rights to the Toolkit but has a potential fix for a bug that he/she wishes to share.

Some background?
Currently our users, who do not have contributor rights, are attaching code files to bugs directly and that is hard for us to integrate into the Toolkit since there is no automated way of creating a changeset to view the diff; Also, if the version they were using was not the latest, the merge is difficult to handle. If the fix is in the form of a Patch created using this tool that will allow us to serve our users better by incorporating their fixes promptly, and hence we would like to make this a part of the standard process for sharing code fixes for Toolkit issues. We are very excited about this tool and we think it will help us get a great deal of bugs resolved and have a more involved Toolkit community. Although, we plan to keep this restricted to fixes for existing components for now. We are holding off on any new components currently and focusing on making the existing controls in the Toolkit stable and feature complete state.

The patch tool may not be the best way to share code samples to demonstrate Toolkit usage but only to fix issues/bugs in the Toolkit.

What does this do?
Creates a diff of changes that you can attach to a bug.

What does the Toolkit team do?
The Toolkit team will apply those changes, review and verify to see if they fix the relevant bug functionality and incorporate it in the Toolkit code.

Download Patch Utility

Please make sure that you uninstall all previous versions of the Patch Utility before installing the latest version. Click here to download Patch Utility Version 1.0.7.0.
Note: Please check this wiki before you use it again since we may make changes to it and would like you to use the latest version.

How do I create a "patch"?

  • Run the Patch Utility and choose “Create a Patch” option to walk through the wizard.
1Create_CreateAPatch.jpg
  • It will show you recent check-ins to choose from. We recommend that you choose the latest version for download to avoid potential merge conflicts.
2Create_ChooseCheckIn.jpg
  • Accept the End User License Agreement which is the same if you were downloading the Toolkit source code from the CodePlex site.
3Create_EULA.jpg
  • Choose the location where the source code will be downloaded and hit Finish. By default, only files in the Development branch will be downloaded. If you click on the "Show Folders to include" link you will see options to download sources from other branches but selecting those will result in a longer download time. Please make sure that you make changes only in the Development branch folder. If you need to make an exception and please contact us by sending an email at ajaxtk@microsoft.com.
4Create_FolderToUnZip.jpg
  • If you check "Open the solution in Visual Studio", it will load the solution so you can begin making your changes. If not, you can navigate to the Development folder, which should be under the patch folder you unzipped it the source code to, and manually open the solution.
SourceCodeDownloadFolderStructure.jpg
  • Make any changes you wish to make to the appropriate files. Please ensure that your changes only address the relevant issue - no extra changes or additions please! Make sure the sample website demo for the changed control works as expected, as well as the automated tests in the TookitTests project.

How do I submit "patch" I have created

  • Run the Patch Utility again and then choose the “Submit a Patch” option to walk through the wizard.
1Submit_patch.jpg
  • Select the folder where the source code was downloaded earlier. The folder you chose in the "Create Patch" sequence above should be automatically chosen for you. If not, use the "Browse" button to locate it.
2Submit_folderPath.jpg
  • The tool will perform a diff to see what files have changed, been added/deleted.
3Submit_DiffingChanges.jpg
  • You should now see all your changes. Note only files included in the project will be shown in the list. Check all those that are relevant files for the bug fix you are targeting.
  • We strongly recommend that you use the Patch Utility to fix bugs in existing components. It is not designed for the following:
  • New components/controls and/or large feature areas
  • Adds/Deletes to files in the bin/obj folders
  • Changes to the Toolkit Solution file.
  • Changes to web.config files.
  • Changes to the csproj files apart from relevant file add/delete updates.
  • Code fixes to answer forum posts
If you need to make an exception please contact us at ajaxtk@microsoft.com.

4Submit_SelectFilesToSubmit.jpg
  • It will also allow you to diff your files to see the changes you made. Using the "Edit Diff Tool" link you can choose the Diffing utility of your choice and compare your files to the original ones.
DiffTool.jpg
  • Provide a description for your changes and your name and email address. We may contact you in case we have questions regarding your fix.
5Submit_FixDescriptionContact.jpg
  • The next screen will show the path to the Patch zip file and automatically open the folder to the zip. You can choose to keep your source code tree or have it automatically deleted. Hit Finish after choosing the applicable options.
6Submit_CreatePatch.jpg
  • On the Toolkit work items page, go to the work item whose fix you have created and attach the Patch zip file created by the utility. Please add a comment to the bug describing your fix. Your fix will be handled for reviewed by the Toolkit team and applied if it fixes the issue appropriately. Please do not create a new work item if one already exists.
SubmitPatch.jpg

How will my patch get applied?

Behind the scenes, the Toolkit team will generate a "ShelveSet"(a changelist that can be applied to the codebase) and review the changes you have made. If all the changes are acceptable, it will update the bug/work item that the patch has been accepted and check in the changes on your behalf. The bug will be closed and the changes will ideally appear in the Toolkit release that follows. If the changes do not seem applicable, we will update the bug with comments on why the patch was not accepted.

How will my work be recognized?

Check out this page.

Other questions?
  • Submitting the patch does not guarantee that it will be picked up and be made a part of the Toolkit codebase.
  • Code submitted using the patch will be subject to the CodePlex Terms of Use just as it would be if you were attaching the code files straight to the bug.

Last edited Apr 14, 2009 at 12:04 AM by BertrandLeRoy, version 33