Development Setup

Topics: Administration, Customizing Orchard, General, Writing modules, Writing themes
May 24, 2011 at 9:56 PM

I continue to struggle with the best setup for orchard development, specifically with a structure for my source control.  My priorities are these:

  • Be able to easily update the orchard source (i.e. pull from codeplex)
  • Be able to keep my custom modules/themes/etc in a separate location from the orchard source
  • Be able to utilize the codegen features

Currently, I'm using the following structure

  • A sub-repository that points to my fork of orchard on codeplex
  • A batch file that creates symlinks for my themes/modules in the /Modules & /Themes directory

The issues that I've run into are these:

  • I'd rather not use a fork of orchard, as that makes updating messy.  However, I don't know how to tell Hg to make a "read-only sub-repository" - i.e. not try to push back to codeplex.  Right now, if I try to create a sub-repo based off the core orchard repo, any time I try to push, it bails on trying to push the sub-repo
  • The symlinks work, however they're a dirty solution.  What I'd like to do is a) have orchard look for projects referenced in my solution or b) be able to specify alternate locations for modules and themes
  • I figure I will eventually run into issues with modifying the core orchard .sln file to add my modules in when i try to update from the base repo

How are other people setting their environments up?  I really want to get a solid environment going.

May 24, 2011 at 10:09 PM

The way I do it is that I have a regular (non forked) enlistment to Orchard. Then, I prepare the Hg setup for my module in a completely separate folder, and only when it's properly setup, I move that folder under [MyOrchardEnlistment]/src/Orchard.Web/Modules. This works perfectly as the two enlistments work independently.

The only issue I see with that setup is that you need one repository per module.

May 24, 2011 at 10:21 PM

Just to be clear, when you (and the docs) refer to enlistments, you're referring to a local clone of the repository, right?  It's been throwing me off, as this is the only project where I've heard references to enlistments.

May 24, 2011 at 10:22 PM

Ah yes, that is a good point. Old habits are hard to quit.

May 24, 2011 at 10:25 PM

You did help me to realize something, though, and that is it seems like hg ignores a nested repository unless it is explicitly stated as a "subrepository".  This would fix my issue with Hg trying to push my sub-repo every time I push the master repo.  It will just make it such that other developers will have to manually check out the orchard repo, which i can live with.

May 24, 2011 at 10:25 PM
bertrandleroy wrote:

Ah yes, that is a good point. Old habits are hard to quit.

Is it a TFS thing?

May 24, 2011 at 10:28 PM

No, it's from before that, from the source control system that was used by MS before that. I think that terminology was also in use with SourceSafe (ew, yes).

Dec 27, 2011 at 2:50 PM

On this same note, but for TFS, it seems like it would be possible to have a development setup in TFS where there is the "core" Orchard site, and then separately maintained "Module" projects (all under 1 TFS Project, just different folders).  Then, create a custom build post-build event which copies the "Module" projects as sub-folders under the main Orchard website.  Sure, this might require that you still need to "enable" the module when you run the site, but at least the module projects can be maintained separately in the Solution.  Actually, this isn't TFS specific at all, it's more just VS Project configuration.

The advantage to this is that your Modules can be built separately and then "deployed" to a QA/STG and eventually the PROD sites which are NOT the same sites that you would be using locally during DEV.  So the local DEV site is just a throw-away project that can be upgraded on a separate schedule than STG/PROD.  In other words, you would never deploy your local DEV site (although you might deploy the Media folder? - not sure yet).

Dec 27, 2011 at 9:26 PM
Edited Dec 27, 2011 at 9:28 PM

I am doing something very similar to the OP, expect i'm not using Mercurial at all. I'm not sure what the point of doing an enlistment is if I'm not contributing code to the Orchard project, and if I'm not using Mercurial for my own projects. There is no point in an enlistment in my case right? 


  • Download and extract orchard source to a local folder. 
  • Create symlinks to my THeme and modules from \Orchard.Web\Themes and \Orchard.Web\Modules
  • (e.g. mklink /D MyTheme c:\svn_projects\mysite\orchard\orchard.web\themes\mytheme\) -- have made a batch file for this so other dev's on the project can set up on their machines.
  • Copy Orchard.sln, and rename the copy to MyProject-Orchard.sln. Store it in c:\svn_projects\mysite\orchard\MyProject-Orchard.sln
  • Create a symlink in \orchard-src-1.3.9\src\MyProject-Orchard.sln that points to c:\svn_projects\mysite\orchard\MyProject-Orchard.sln


Dec 27, 2011 at 9:46 PM

The point of doing an enlistment: getting easy updates, including on subrepositories. Pull, update, done.

Jan 3, 2012 at 3:39 AM


I am also trying to setup a 'teamed' dev environment for Orchard-based web-sites. I recognize the many paradigm differences between Mercurial and TFS so I've decided to manage Orchard development entirely within Mercurial and manage closed-source projects entirely within TFS.

However, the fundamental issue that occurs to me is the management of deployed versions. That is, relying on branches as a means to 'save off' a copy of the final release version of a customized instance of Orchard is not a reliable (manageable) mechanism in a production/commercial dev-team enviroment. It seems more realistic to utilize 'local' forks of our customized instances of Orchard as our release versions (essentially an archived version we can base new release versions on).

Essentially, this gives us a tree of main lines:

1. (root) Our internal set of 'core modifications' to the core Orchard platform maintained in our development environment. This is a main line that derives from the ongoing progress of the 'tip' of the Orchard main line on Codeplex.

2. (subtrees) Deployed versions of our customized development versions for various engagements and venues that are represented as branches from our internal main line. Our released and deployed versions of these customized instances would be what we fork off to 'release versions' according to our release schedule.

So what I need to understand is:

1. Maybe there's a better way to concieve this structure?

2. It seems that what I need is a local 'repository' that acts as an 'orchard core' mainline that our 'core modifications' main line branches from and receives merges from. Then our engagement mainlines branch from the 'core mods' mainline and receive both 'orchard core' and 'core mods' merges. And customizations from the engagement mainlines are created on 'feature' branches that could be merged back to our 'core mods' mainline as necessary.

3. That gives us release versions for each of the engagement mainlines that are forks of those mainlines, as well as forks of our 'core mods' mainline as release versions.

Presuming this makes sense to begin with, my main question is about this:

It seems like what I need is a 'local repository' that is the starting point for our developers to base their local mainlines on. And that local repository has to be  'somehow related' to the mergable clone of the Orchard project on codeplex.

So if I start with a clone of Orchard (that I can update as Orchard versions change), what is the proper way to create a 'local repository' that our developers recognize as their 'default branch'? Is it a 'clone of a clone', a 'sub-repository', a fork of the local orchard clone?

Something like this...

                                                                                                                     feature br--->
                                                                                                                   /                       |   
                                                           engage 2------------>----------->---------------->----->....
                                                          /                                /                                                         |
                                                         engage 1----------->----->-->----------->...                    |
                                                       /                                /        /       |                                          |
                                                     engage main------->----->---->-->----------->----------->...     
                                                    /                                /       /              /                  /
                                                 core mod main----->---->--------->---------->...
                                                /                                       /                                /
                                              mainline clone---------->--------------------->...
                                             /                                     /                                  /






Jan 3, 2012 at 5:10 AM

Looks good. Yes, I would make each engagement a clone of the mainline clone. That's what I'm doing with one of my customers and it works well. We also try to integrate modules as subrepositories of the mainline clone when we can.

May 17, 2012 at 9:14 AM


could you please share some more detail about the process your team is working now with orchard and source control and how to set it up? We have TFS as our primary source control system. Now we are switching part of our development to orchard (because we think that orchard is great, of course ;-).

May 17, 2012 at 9:12 PM

What kind of details? Any specific questions?

May 17, 2012 at 10:26 PM

I had not a solution of some specific problem/detail in mind and do not have "specific" questions right now, just looking for some "specific best practices" :-(.
We are evaluating our possibilities to setup orchard based development for team work. And the team just want to start real development as soon as possible :-)

It would be very helpful if orchard-skilled teams could share their knowledge about their own team development setup. As i wrote, we are using TFS at the moment and i am not sure how to set the whole thing up (orchard vs tfs vs mercurial). kimballjohnson for example was writing about his plans for their team development setup and i would like to know some details about the results.

For now our idea was essentialy the same as kimballjohnson's - Keep mercurial for the shared orchard part and put our projects into TFS and keep with workitems based management. The question is - how to do it.

May 19, 2012 at 8:22 AM

bertrand could you please explain how you would do the following? :

clone this module into my orchard source code enlistment in a way that keeps the possibility to do uptades to orchard and modules as well. Enlistment of the module contains the module itsef and unit test project.

My idea is to mantain a functional and updatable repository with mercurial and the "implemetnation" projects in TFS and, if possible without much struggle, in mercurial too. That means we could keep doing our daily developer's work using TFS and pull/push to/from codeplex using mercurial (tortoisehg). Does this sound possible and reasonable, or is it a bad idea? 

for orchard and TFS i found the following blog from steve taylor. It's not very detailed, but the only one i found about orchard and tfs: 

May 19, 2012 at 7:53 PM

I would hide that directory from Mercurial. That should take care of it.

Sep 12, 2012 at 11:43 PM


I've been trying to maintain the branch/fork plan I added to this thread back in May.

I'm finding mercurial a little too delicate to manage and not particularly 'adoptive'.

So I'm trying out the TFS/Mercurial solution.

but, like the others above, I'm finding that none of the explanations are truly informative.

So lets presume:

1. I'm not going to update/push/synchronize to the orchard codeplex source.

2. cloning Orchard to a local repository (forking the source/ enlisting??) and cloning again to another orchard-mercurial-mainline is straightforward.

3. Keeping a (separate?) mainline, branches, environments, deployments, etc. in TFS is an established practice.

so the issue boils down to the bridge between the orchard-mercurial mainline and the orchard-tfs mainline.

considering this is a one-way path from codeplex to tfs so that we can obtain the new orchard functionality when and if we want to....

How do we synchronize between the mercurial and tfs mainline?

in my graph from my post in May, my concern focuses on the pull from mainline-clone to 'core mod main'.

if we were able to keep mainline-clone under mercurial control and also make it the root line in TFS, then we could perform one-way merges to the 'core mod main'.

I believe this is what you were 'kind of' referring to when you said, 'I would hide that directory from Mercurial.'

Are you speaking about a 'hide' functionality in mercurial? or do you mean copying the mainline-clone to 'core main mod' manually (beyond compare?).

Or what would you suggest more precisely?



Sep 12, 2012 at 11:46 PM

How do we synchronize between the mercurial and tfs mainline?

I don't know. I never use TFS. hg update?

Are you speaking about a 'hide' functionality in mercurial?


Sep 14, 2012 at 12:17 AM


I appreciate your help on this.

I'd also like to introduce this very informative link to a discussion on Stack Overflow:



Jan 3, 2014 at 5:20 PM
With the switch to Git, this workflow seems to break down. Bertrand, what's your process now? Or am I missing something with Git?
Jan 4, 2014 at 8:50 AM
Edited Jan 4, 2014 at 8:50 AM
I don't see what's different with Git. How does it break down?