Upgrading a Community Server Site to a New Version of the Product
With the recent release of Community Server 2008.5 SP2, I've heard a lot of questions about how best to upgrade a customized Community Server site to the latest service pack. Therefore, I hope to spell out the method that we at ATGi use when upgrading custom sites for our clients.
When I say "custom sites", there are really four levels of customization that could be performed in Community Server. Each level involves more complex customization and deeper integration with the Community Server code provided by Telligent. For the purposes of this article, these levels of customization are:
-
Control Panel Customization-this is the most basic level of customizing Community Server. You are at this level if the only changes to your application that you have made have been done in the Control Panel. You haven't changed any of the files that came from Telligent, much less added custom code to the application.
-
Theme Customization-this is the level at which most communities are customized. You are at this level if you have changed HTML/ASPX pages that came with Community Server, moving controls on certain pages, adding controls to show different data on pages, and so forth. A Level 2 customized site doesn't include any modifications to code provided by Telligent, but may call web services exposed by the application.
-
Additional Code Customization-this is level of most sites built by ATGi. At this level, we have modified the site's theme by altering ASPX files and creating new ones. We have also created additional .NET assemblies that extend certain controls provided by Telligent, and we have configured the community to use custom providers, modules and so forth. All of this is done, though, without modifying the base Community Server assemblies provided by Telligent.
-
SDK Customization-at this level of customization, you have cracked open and changed the Community Server SDK, so all the assemblies provided by Telligent are your own custom versions. I don't recommend this level of customization at all, since you can perform just about any customization that you want at level 3. Many developers dive right into the SDK to customize Community Server, and it works just fine until you get to the stage you're at right now--trying to upgrade your community to a new version of the product.
Level 1 sites are relatively simple to upgrade. I recommend simply exporting your theme configuration file and using Telligent's provided upgrade tools. (Make a backup of your site first, of course.) Once the upgrade tool is complete, you shouldn't need to do much else; the site should "just work" on the new version.
Level 2 and 3 sites are more complex to upgrade, but there is a standard process that I use that makes the operation relatively painless. The process requires performing a three-way merge on all of the site's theme files. If your community is in a decent source control system (Your community *is* in source control, right?) then the process isn't difficult to perform. (It's tedious, sure, but not difficult.) In the event that your community is not source-controlled, I'll run through the complete process:
-
-
Commit the web project from this original version to your source control system. (If you are already using SCM, then just find the changeset/version number corresponding to this original check-in.) We're going to refer to this version of the code as the base version.
-
Create a branch of the base version of your code in your source control system. This branch will be used to store the original Community Server code from Telligent, and you should never write your own code in this branch.
-
Check out the entire branch and overwrite all the files with those in the latest Community Server service pack. Depending on the source control system that you use, you may need to add or delete certain files. You may also want to rename certain files if it is obvious to you that a new file has largely similar content to an old file that was deleted. Renaming files in this way could help your SCM better merge in your custom theme. Once you're done overlaying the CS service pack, check in all files in the branch.
-
On the main code line (the one you branched from), check out all files and overwrite them with your customized Community Server site. Again, you may need to add, remove, or rename files for the source control system. Once you have made the main code line exactly match your custom site, check it in. (If you are already using SCM, you probably don't need to do anything in this step. The latest SCM version of your site will work.)
-
Now, using your source control tool, perform a merge of the service pack branch into your main code line. If you've set everything up correctly, your source control system should be smart about presenting you with only conflicts in the upgrade--lines of code that you customized and that were changed by the service pack. You'll need to examine these conflicts one-by-one and resolve them manually. (This is the tedious part!)
-
Once you have resolved all merge conflicts, you should have an upgraded version of Community Server that includes your customizations. Make sure that your site is running against the new Community Server assemblies, test it thoroughly, and you should be done!
For level 2 and 3 custom communities, this process should be all that you need to do in order to upgrade your application. With level 3 communities, you will need to verify that your custom code executes properly, of course. I've performed upgrades of Community Server sites in which the new version of the product no longer called methods I was depending on, so you need to be wary there. But for the most part, this process will give you an upgraded Community Server site costing you as little time and pain as possible.
Make sure that you are using a good merge tool. I prefer DiffMerge and P4Merge, both of which are free.
Lastly, if you have a level 4 site in which you've customized the SDK, you will need to perform the same basic steps outlined here. The only difference is that rather than merging only the web files, you need to merge every file in the SDK. If you've made a substantial number of customizations, then you may have a very difficult time reconciling code changes, moved files and so forth between one version of Community Server and the next.
This pattern is essentially the "Third Party Codeline" configuration management pattern, explained in great detail in Software Configuration Management Patterns. I highly recommend this book for learning how to manage your codebase. And if you want to master the ins and outs of Community Server customization, I recommend that you take the Mastering Community Server Class being offered at ATGi in Columbus, OH on April 27-29, 2009. In the class, you'll learn about many other considerations and design principles that will help you build a highly customized community that is relatively straightforward to upgrade.