Contributing to WebsitePanel using Mercurial
The best way to contribute a new feature or a bug fix to WebsitePanel is by creating a fork, committing your changes to it and then submitting a
pull request using CodePlex's Mercurial support. Note: If you don't already have a working knowledge of Mercurial, we suggest taking a look at
hg init and the
Mercurial book. Watch the free 30 minute video on using Mercurial with Codeplex
[TBD: Look at our Code Conventions and follow them.]
Setting up your WebsitePanel development environment
The first thing you'll need to do is sign in to
CodePlex (or create an account) and navigate to the
WebsitePanel’s Source Code page and launch "Create Fork" wizard by clicking on the corresponding link.
Your fork will contain a copy of the WebsitePanel’s source code on CodePlex that you can commit to before it is merged in to the main project’s repository. You will be asked to create a name and description for your fork. It pays for you to give
it a descriptive name that explains the purpose of the fork and provide a description .
Once your fork has been created, you can pull changes from it on to your local computer, make your changes and
push them back up. To do this, you will first need to install a Mercurial client. For this example we will use TortoiseHg which can be downloaded from [url:http://tortoisehg.bitbucket.org]. Once installed,
you should create a folder where you can check out the project’s source code from the fork you just created. In this example, we created a folder in C:\Projects\Codeplex called "CloudAPIContrib". To check out the code, right click on the folder
and select "TortoiseHg" then "Clone".
This will bring up the "Clone" dialog. In the "Source path" box you should enter the URL to your fork.
This can be found back on the WebsitePanel "Forks" page at [url:http://websitepanel.codeplex.com/SourceControl/network]
This will take a few minutes to get the source code downloaded to your computer. Once completed, the C:\Projects\Codeplex\CloudAPIContrib directory should contain all of the source codes from the fork you specified.
Next, you can work on the feature or bug fix that you want to submit to the project. In this example, we just going to add a sample interface for new service provider. Once you have made your changes, you can right-click on the CloudAPIContrib folder and
select "Hg Commit" from the menu.
This will bring up the commit dialog where you can review the files that you've changed and enter a commit message. Once you've entered the message, press Commit button in the bottom-left corner. If you've added any files then you'll need to make sure you
checked those you want to commit.
Note: If this is the first time that you've tried to commit to a Mercurial repository you may get a warning about "Invalid Username". If this happens then you should open the TortoiseHg settings and under the "Commit"
section enter your name and email address in the "Username" box. The usual format is "Firstname Lastname <firstname.lastname@example.org>" (eg "Full Name <email@example.com>").
At this point, you have committed your changes to your local repository. You can view them by right clicking in CloudAPIContrib folder and selecting "Hg Workbench". This will bring up the log viewer where you can see the commit
that you just made.
Pushing changes back to Codeplex
You can now push the changes back to your fork of the WebsitePanel project on CodePlex. From within the Hg Workbench you can do this by selecting the "Push" button (it looks like two yellow cylinders connected with small green arrow pointing upwards)
Once confirmation dialog appears you then click “Yes” button and afterwards you will be prompted to enter your Codeplex username and password to commit the changes to the repository (this may take some time depending on the size of the changeset).
You can now submit a pull request back to the project coordinators. This is done via the Codeplex by clicking "Send Pull Request" hyperlink next to the name of your fork.
You should title and provide details about the changes that you have made. Once you click "Send", this will send an email to the project’s coordinators who will review your changes and either provide you with a feedback or, if accepted, merge
them in to the main repository.