Project Branching
Branching is a fundamental operation in the CMS and one that all content creators and managers should be familiar with. The goal of branching is that it allows content creators to work with a clone of an asset, one that is in production for example, to make changes in the CMS and preview those changes either in the CMS or in different published environments without impacting the production content.
A similar facility exists, and for the same reason, when it comes to your CMS implementation code. Project branching allows you to:
- make a clone of the entire project folder
- make changes in either branch;
- compare and merge between branches; and
- specify which branch of the code to use for each workflow state (which more often than not corresponds to a published environment).
This feature is critical for phased implementations or that are looking to make significant changes with content already in production.
There are a couple of different strategies you can use when it comes to project branch.
Trunk-based Development
This strategy has all active development happen in the original project folder. In Crownpeak DXM, this is a shared resource as all implementation code is managed directly in the CMS rather than in external or local developer environments.
When development has reached a significant point, a stable feature release for example, create a project branch and label it. No changes, other than urgent fixes/patches should be made to the branch.
I find that this strategy is the easiest to work with, but your experience may differ (let me know in the comments).
You can read more about this general strategy here: trunk-based development.
Branch-based Development
This strategy has all active development happen in the latest, tip or leaf, branch. When the implementation has reached a significant point, create a project branch, which will be the new tip/leaf where ongoing development towards the next release happens. Both the previous and the new tip branch are labelled appropriately. As with trunk-based development, only make urgent fixes/patches to the release branch.
A common approach when using this strategy is to name the branch with a suffix indicating which is the tip: something like 1.0-DRAFT. When the release is finalised and the new tip branch is made, the branch is renamed to 1.0 and the -DRAFT suffix is moved to the next branch.
Branch targeting
Once you have more than one branch of a project, the «Site Root» properties panel is where you can set the project branch, if any, to use for each workflow state. The workflow states presented in the panel are derived from looking at the workflow(s) in use by assets under the site root.
Whichever branching strategy you use, when a release point comes up, you can go to the the «Site Root» properties panel again and update the project branch references.
NOTE: Doing this will not make any changes visible in any published environments, you will need to trigger publishing either through workflow events or by using the republish command on the site root folder.
Branching with Component Library
Component Library has a configuration asset located at «{project_root}/Component Library/Component Library Config». This asset specifies the various folders that Component Library should use and reference, including the Library folder.
The Component Library is deliberately installed under the project root folder so that when you branch a project, you get a clone of the Component Library definitions as well as the generated Component Library artefacts such as C# source files and templates.
Although component library definitions are cloned into each project branch, the branch compare and merge tools only operate against the Library, Template and Model folders. This limitation makes it very difficult to reconcile changes to the definitions files across branches. For this reason, I strongly recommend that you:
- Use a trunk-based branching strategy; and
- Only permit changes to component library definitions in the trunk.
If you find you need to make changes to a release branch that includes changes to the component library definitions, the approach would make the changes in trunk and then either:
- Manually copy the changed library classes to the release branch; or
- Use project merging to create a sub-release project branch.