Using mq to manage local OSS code.

Recently I've started working with the Orchard CMS open source project. As part of this I needed to alter the code base to suite my environment. So how do I

1. Manage local / my own changes to the source.
2. Refresh my tree when the source updates.
3. Take changes from other forks.

This particular project is using Mecurial (hg), so I can leverage the MQ extension to manage my local code.
I use TortiseHg to work with HG repositories, I'm not really a command-line kinda developer.

Enable MQ extension

Firstly, enable the MQ extension. Be sure to enable the extension in your global settings. More on patching from TortoiseHg Doc.

Clone the repo

The folks on the Orchard project use forks for managing contributions, since this is a local copy, I don't want a fork, just a local clone will do. Otherwise I'll be adding to the noise on the project by holding a fork for an extended time period.

Create your patches repo.

With MQ enabled, you now have a little diamond in the tool-bar. Click to view MQ stuff. Now create a MQ repo. This creates a new hg repository inside the .hg folder, called patches. Since this is itself a repository, working with it is just like working with another repository.

Note: it is NOT a sub-repo, I got confused thinking I could work with the MQ repository like a sub-repository... that ended in tears.

Make a change as a patch.

My first change was to update the azure project. Make the change, but do-NOT commit. Rather use the diamond  click 'new patch' and then commit using QNew. 

I find it useful to view the patch queue, use View--> show patch queue. Another check is to actually open the patches repository, find it inside the .hg folder and open in Tortoise, you should see your patch has been committed.

Update from main repo.

I can now, just like normal, pull from the main repository to get any changes.
before pulling, I like to undo my patches, then re-apply the patches after any updates. Then I can check if each patch is still relevant, and I can update each patch (if needed) to reflect the refreshed code.

Taking changes from another fork.

Orchard uses forks for contributions. Since a fork is just a clone on CodePlex, I can clone a local copy. From Tortoise I can create a patch for a particular change set using r-click export. Then in my local repository, I can import this as a patch using Repository --> Import.

WARNING: be sure to import to patches, not the repository itself.

Extracting a patch.

Any change I make on my local clone, maybe useful as a contribution back to the Orchard project. This can be a bit of a problem, since I may have a few local patches that I don't want to contribute back (because they have no use) to the project. The easiest way I've found is to:

1. Fork Orchard and get a local clone (normal for Orchard). Open my fork clone.
2. Use repository --> import and locate the patch in my local/.hg/patches folder.
3. Import the patch to the Working Directory. Do-not import directly to repository.
4. Fix the patch if needed, and commit the change set.
5. All the other bits like running unit tests; push to my fork; submit pull request.

Well that's the plan, will have to see how it goes over time.