Sitecore Upgrade : The Art of War

When you enter a battlefield, be it land, mind or disk, be aware (wink):

"No plan survives contact with the enemy"
-Helmuth von Moltke the Elder

That's not to say you should have no plan though. Quite the contrary:

"Victorious warriors win first and then go to war, while defeated warriors go to war first and then seek to win."
-Sun Tzu

The War of the Folders

Starting at the top, you've got to upgrade the updater so you can install updates. You'll be copying in new files. You've got to run SQL scripts. Then you fix everything that broke. If you cross more than one point version, well then you're doing this all, multiple times.

If you've done yourself any favors, you've downloaded the packages, scripts, updates, a "Site Root" zip of the version you're installing and last but not least, the steps for each upgrade path and broken them up into folders like "7.0 to 7.1". You should also consider removing Sitecore from your solution (except configs and binaries) and publish onto a stock installation. In my experience, you're best bet is to upgrade to the nearest point version and jump from initial release to initial release. 

Hopefully your config modifications from a stock build will be in a separate "include" config far away from the ground-zero. In a quiet, zen-like state. This state is within you. It is you. Well, at least, if you want to have any hope of survival. But really, this is because the heart of the battle lies in preventing a cataclysmic collision of config files. In your hands are your helmet, sword and shield: Winmerge, Visual Studio and Git.... Silence. My pupils dilate and the caffeine is flowing.  

"He who knows when he can fight and when he cannot, will be victorious."
-Sun Tzu

At first contact, you're looking each other square in the eye. There's no illusions about what you've gotten yourself into. You've entered the Thunderdome (shout out to all you Aussies). It's looking at you. You're looking at it. Neither speaks. Neither blinks. You breath deep and dive in. You get a quick thrill knocking down the first few dozen line ending changes. Alt-Down. Alt-Left. Alt-Down. Alt-Left. Oops, CTRL-Z. But after a time, you're just playing a two-bit game of Chuck Norris, Roundhouse Config Kicker. WHACK! WHACK! WHACK! WHACK! You become numb. The tension is worn away in an anti-climactic grind.  

Suddenly something pops up. You find the new default values have changed. Oooh. Your mind is mildly sated. A small meal though. No more.

"He who is prudent and lies in wait for an enemy who is not, will be victorious."
-Sun Tzu

As time wears at you like a sweaty shirt, you ease new entries into place. You delicately tip-toe through custom config sections. Bob and weave around modules and rewrites. Man-handle handlers and services. You win some, you lose some but you live to fight another day.

Apocalypse How

In the process of upgrading a system through 7.5 there's a slight bump in the road: xDB. Or rather, MongoDB. The xDB overview doc is a good start to understanding what's going on but long story short, you need to download, install, configure, run as a service, setup connection strings to it, modify the analytics settings, setup at least one goal so that it begins tracking (I couldn't find an article anywhere explaining this) and last but not least deploy it. 

Like a good soldier, Dan Solovay has written about Sitecore moving to xDB and a great piece on MongoDB with Sitecore and Nick Wesselman has a whole series on it. 

The highlights are the four "Analytics" databases (analytics, tracking.live, tracking.history and tracking.contact) that run on MongoDB and one "Reporting" MSSQL database whose file is named "Analytics". It's the one that comes with "Core", "Master" and "Web". That's confusing, you might say, why isn't it named "Reporting"? Because it's your old analytics database that's been converted. Well, I mean that you're going to convert/rebuild it right now (which is what the reporting.secondary connection string is for.). If you need help, tactical options are available. 

Ok, let's assume you figured all this out and your local environment works, what's going to happen when you go live? You have to deploy MongoDB somewhere secure, that your other environments can access. Maybe there's a CLOUD solution for all that BIG DATA, but I have to roll my own so I wouldn't know. If you decide to manage it yourself, MongoDB has a good deal of documentation but it's might require some translation (they've been changing their API with newer versions too) so you'll be spending a good deal of time googling, guessing and testing.  

If you make it all the way to Sitecore 8, which is what I'm doing, you should also be aware of a new tool being added called Phantom.js. You should download this from Sitecore's Dev site and not the product's site. It's contents are added to the /data/tools folder which is where some core pipeline expects it to be. This is used to take screenshots when the system is testing, or as I found out, it runs when I update presentation details on standard values.  

Enemy at the Gates

If you made it this far, "Achievement Unlocked: Dragonborn". But don't get too comfortble. You're out of the quagmire but your still in the trenches. The light at the end of the dark tunnel though, is an end-boss. One with more comebacks than King Koopa: IIS. 

You dive into your foxhole, reach for Visual Studio, load your solution, cock back NCrunch and start launching builds, like a battery of artillery fire. 

Publish-Development..... The output window gives you a mime's version of atomic gears grinding. The silence is deafening.

MISFIRE: Sitecore namespace cannot be found. Awwwrrrr. (update the reference to new binary). 

Publish-Development..... 

MISFIRE: awfffwwah (projects target the wrong .NET version) 

Publish-Development.....

MISFIRE: Could not find add method: SetCommitPolicy. Should I call in air support? (squints. raises eyebrow. scratches head. glances at Stack Overflow) 

Publish-Development.....(sound of a missile launching)

SUCCESS! A DIRECT HIT! 

You're palms are sweaty, you alt-tab to the nearest browser (never to IE though, just out of spite). CTRL-F5. 

"Config Error Cannot read configuration file because it exceeds the maximum file size"

Pfffwa. Buh. Muh... Guh...

REALLY?!?! Not a mis-spelling. Not a double-entry. NOT EVEN A SINGLE MISSING BINARY?!?! Wow. You NEVER, and I mean NEVER see that one coming. 

"Thus, what is of supreme importance in war is to attack the enemy's strategy."
-Sun Tzu

So now you're on an epic side-quest to peel off as much of the config into includes as possible. Oh don't forget, if you use config transformation (.NET not Sitecore), the build can't follow Sitecore's config references to the "include" config files. They haven't been joined in holy matrimony yet so be aware of that minefield. If you need some suggestions on what to move, I think it makes sense to pick sections that don't differ by environment but are fairly large. It was enough for me to move <databases>, <events>, <mediaLibrary> and <log4net>. For guidance just follow how the commands.config is managed.

Back to the future, you're heart is beating intensely. You straighten up in your seat. CTRL-F5. We've got to get it on the run! Grab the exception and find the nearest google. Furiously read the saveragery of battles past and learn from the bloated body of blogs and Stack Overflow. One, Two, Ten, Infinity. Found it. What was .... awwwwrrrrr...my fault. 

"The supreme art of war is to subdue the enemy without fighting."
-Sun Tzu

All Quiet on the Testing Front

Like a fever breaking, the page loads. You can't hardly believe you've done it. It's only one battle in many for victory but at least it wasn't Pyrrhic. Now that's not to speak of all the features that aren't quite working correctly like the "Experience Editor" (How do you choose which site you want to edit from the home page?). Or the Lucene indexes (I was using the scSearchContrib which is now deprecated). And let's not forget, caching (I had it customized).

Reconciliation

The update process is a work in progress but know that as technology advances:

"The wars of the future will not be fought on the battlefield or at sea. They will be fought in space, or possibly on top of a very tall mountain. In either case, most of the actual fighting will be done by small robots. And as you go forth today remember always your duty is clear: To build and maintain those robots."
-The Commandant, head of Rommelwood Military School 

In work, as in war, although the best laid plans of mice and men often go awry, this is your upgrade guide, so you won't be forced to hire Seven Samurai. 

"Make an upgrade plan if you're soon to, and defeat your chances of ending with Seppuku."
-Mark Stiles