Contributing to MvcContrib using Mercurial

The best way to contribute a new feature or a bugfix to MvcContrib is by submitting a pull request using CodePlex's Mercurial support.

Note: If you don't already have a working knowledge of Mercurial, I suggest taking a look at hg init and the Mercurial book.

Watch the free 30 minute video on using Mercurial with Codeplex http://tekpub.com/codeplex

Look at our Code Conventions And follow them.

Setting up your Mercurial development environment

The first thing you'll need to do is sign in to CodePlex (or create an account) and navigate to the MvcContrib source control page at http://mvccontrib.codeplex.com/SourceControl/list/changesets and select "Create Fork".

01_SourceControlList.PNG

You fork will contain a copy of the MvcContrib code on CodePlex that you can commit to before it is merged in to the main MvcContrib repository. You will be asked to create a name and description for your fork. I just named it with my initials, but in reality you would probably give it a descriptive name that explains the purpose of the fork.

02_CreateFork.PNG

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. The command line mercurial client is excellent, but for this example I will use TortoiseHg which can be downloaded from http://tortoisehg.bitbucket.org.

Once installed, you should create a folder where you can check out the MvcContrib code. In this example, I created a folder in C:\projects called "MvcContrib". To check out the code, right click on the MvcContrib folder and select "TortoiseHg" then "Clone".

03_ContextMenu.PNG

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 MvcContrib "Forks" page at http://mvccontrib.codeplex.com/SourceControl/network

04_MyFork.PNG
05_CloneDialog.PNG

This will take a minute or so. Once complete, the MvcContrib directory should contain all of the source code.

If you're using the command line client, the equivalent command would be:
hg clone https://hg01.codeplex.com/forks/jeremys/JSMvcContrib MvcContrib


06_DirectoryListing.PNG

Making Changes

Next, you can work on the feature that you want to submit to the project. In this example, I'm just going to add some XML-Doc comments to a file.

Once you've made your changes, you can right click on the MvcContrib folder and select "Hg Commit"

07_ContextMenuCommit.PNG

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 the commit dialog in the top-left corner (or hit ctrl+enter). If you've added or removed any files then you'll need to make sure you press the appropriate "Add" or "Delete" button.

08_CommitDialog.PNG

If you're using the command line client then the equivalent commands would be:
hg addremove
hg 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 "Forename Surname <my@email.address>" (eg "Jeremy Skinner <jeremy@ThisIsNotMyRealEmailAddress.com>").

09_Username.PNG

At this point, you have committed your changes to your local repository. You can view them by right clicking on the MvcContrib folder and selecting "Hg Repository Explorer". This will bring up the log viewer whereyou can see the commit that you just made.

10_Log.PNG

Pushing changes back to CodePlex

You can now push the changes back to your Fork of the MvcContrib project on CodePlex. From within the Repository Explorer you can do this by selecting the "Push" button (it looks like a small green arrow pointing upwards)

11_Push.PNG

You will be prompted to enter your CodePlex username and password. Once entered, your changes will be pushed up (this may take some time depending on the size of the changeset).

If you're using the command line client, the equivalent command would be:

hg push


You can now submit a pull request back to the project co-ordinators. This is done via the CodePlex UI by selecting "Send a Pull Request" next to the name of your fork.

12_PullRequestLink.PNG

You should enter details about the changes that you have made. Once you click "Send", this will send an email to the MvcContrib co-ordinators who will review your changes and, if accepted, merge them in to the main repository.

13_SendPullRequest.PNG

Last edited Mar 19, 2010 at 12:28 PM by erichexter, version 10

Comments

NQKPhuong Sep 3, 2012 at 4:00 AM 
I couldn't clone as described and got error 255 instead.

mcbros Jan 10, 2011 at 4:45 PM 
very nice quick overview, served great in my first commit. Thanks!

purekrome Mar 11, 2010 at 1:42 PM 
Yep! good write up! :)

sdhebert Mar 9, 2010 at 1:22 PM 
Thanks Jeremy - nice writeup!

JeremyS Mar 9, 2010 at 8:15 AM 
Good suggestion - I've added a link to hginit.

rockon1119 Mar 9, 2010 at 4:09 AM 
The Mercurial book is a great reference. If you don't have time to read the book, and would do better with a website, http://hginit.com/ is another good tutorial on getting started with Mercurial.