How to contribute to an Open Source project on CodePlex
Who is this for?
This document is for people who want to contribute patches to an Open Source project on CodePlex, but are not developers or coordinators on the project.
Get the CodePlex Client
Download CodePlex Client (installation instructions
Install a diff/merge tool
You will need to install a diff/merge tool in order to be able to validate your changes. Our configuration
information contains pre-canned configuration items for many free (and a couple for-pay) diff/merge tools. I would strongly recommend you choose a tool which does 3-way merges. I personally use and love TortoiseMerge from TortoiseSVN. If you don't know which one to choose, you might start with that one.
Get the source code
- Open a command prompt (Start -> Run -> cmd.exe)
- Create a directory for the source code
- Run the checkout command
C:\> md MyProjectSrc
C:\> cd MyProjectSrc
C:\MyProjectSrc> cpc checkout MyProject
The checkout command requires a CodePlex project name. You can find the project name by looking at the project's URL. For example, the ObjectBuilder Dependency Injection project has this URL:
The project name is ObjectBuilder. If you only need a part of the source, you can specify that with the :/ syntax, like:
cpc checkout MyProject:/trunk/src
Build the project
How you build the project will depend on what type of project it is. For projects that are done with Visual Studio, for example, you will open the .sln file and build it inside of Visual Studio. Ensuring the project builds okay is critical before you contribute.
If you can't get the project to build, ask the project coordinators/developers what's necessary to get it to build.
What are you going to work on?
Sometimes you want to work on a cool new feature. Sometimes you want to fix an annoying bug. All CodePlex projects have an issue tracker where bugs and features are stored. For example, here is the issue tracker for the CodePlex Client: http://www.codeplex.com/CodePlexClient/WorkItem/List.aspx
. Even if you want to work on something that's not in the issue tracker, you may want to open a new issue tracker item to describe the work you're doing.
When working on a bug fix, it's wise to make sure you have a clean and new copy of the source code. That means you should use the "cpc update" command to get the newest source, and "cpc status" to ensure that you don't have any pending changes that aren't appropriate for the bug in question. If necessary, you may even want to delete the source code directory and re-check it out.
As a helpful hint, when fixing a bug and submitting it via a patch, it's considered "good form" to make as few changes as possible to fix the bug. Just as important, respect the coding style of the original code (tabs vs. spaces, curly brace placement, etc.). Reformating the files into your own style will just annoy the developers on the project, I promise you. :)
Now... fix the bug!Time passes...
Making the patch
After you've fixed everything up, use the "cpc syncup" command to find your deleted and added files, and make sure you're up to date with the newest copy of the source code. Then run the status GUI with "cpc status /gui". This will show you all your pending adds, deletes, and modifications. You can double click on any file that's in the "Modified" state, and it will launch your diff tool. If you find files in the "Conflicted" state, that means they have been touched by both you and someone else; double clicking on these will launch the merge tool which will allow you to fix the conflict.
When you are happy with the state of your changes, run the makepatch command:
cpc makepatch C:\MyPatch.xml
This will write a patch file which describes all the changes you've made.
Uploading the patch
Visit the project page, click on the Source Control tab, then click on the Upload Patch link. In the Description field, fill out a description of the work that was done in the patch. Use the "Browse" button to find the patch XML file you just created. If the patch fixed any work items, be sure to enter their number(s) and add them before submitting the patch.
Sit back and collect your kudos. :)
This document borrows from Scott Hanselman's excellent blog post How To Contribute A Patch To An Open Source Project which is licensed under Creative Commons.