TIL Thursday: What It's Like to Migrate an SCA Site to Mont Blanc

Back in February, we announced the release of Mont Blanc, the latest in a series of updates to SuiteCommerce Advanced. The release added a lot of important features, such as quotes, password protection and key integrations.

As these updates aren't managed, you're required to do some work yourself if you want to migrate. While we have documentation on migrating to new releases, you may have apprehensions about doing it: curious to know what it's been like for others before doing it yourself.

At SuiteWorld, we made contact with Joel McConaughy of JHM Services LLC who recently took the steps to migrate an SCA site from Denali to Mont Blanc. I wanted to find out what his experiences were and if he had any pearls of wisdom to share.

Interview

Hi Joel. Can you tell me about the site you were migrating?

We were working on Lindemann Chimney Company. Through their SuiteCommerce Advanced site they offer a number of chimney and fireplace-related products for chimney sweeps.

What made them want to migrate from Denali to Mont Blanc?

There were two driving factors: one was to 'keep current' and use the latest code updates available; the other was to adopt new functionality. In particular, Lindemann were interested in two Mont Blanc updates: quoting and Google Tag Manager.

How did you prepare for the update?

After downloading the Mont Blanc source code, we ran three diffs:

  1. Denali source code to Mont Blanc source code, to see the changes that had been made
  2. Denali source code to the Lindemann customizations, to refresh ourselves on the changes we made
  3. Lindemann customizations to the Mont Blanc source code, to give us an idea about the types of changes we would need to make

What did you find out?

It was the most time-consuming aspect of the migration but it showed us where we needed to rework our code. While a lot of changes in MB were additive, there were some logic path changes that needed to be made. We also realised we needed to change how we do overrides.

What do you mean?

When we customized the site, we had done a lot of wholesale overrides of modules, and this became problematic. So, in some cases we had taken an entire module, copy and pasted it into our customizations directory, and then modified it. Because of this we had to refactor a lot of our code so that the overrides were file by file. When we did this, it became easier to understand the changes we need to make.

So if you could go back and change things you would?

Yeah. SCA makes it easy to manage overrides for individual files so it would be best to take advantage of that. The documentation on the best practices for customizing the code is really key. Also, the fact that SCA uses semantic versioning and modules are broken down quite granularly makes the process a lot easier.

What are your best practices for handling customizations?

We think it is really important to have a clear separation between modules that are overrides and those that are custom. We require all of our developers to prefix overrides with Override. before the module name. Not only does it make it obvious to existing developers what's custom and what isn't, it makes it easier for new developers to get up to speed. We have those in one directory and the customizations in another.

The other thing we require is that our developers is version control. We use Gitflow to track changes and all devs must ensure that their changes don't break the tree. We consider version control very important and it's certainly something we'd recommend other people use.

Were there specific areas of the code that were challenging?

ItemDetails was, as was Facets. In Facets.Browse.View.js we had some code that was a category manager module similar to the content manager in SiteBuilder. We had to walk the code line by line, and digest the logic changes and rewrite them for Mont Blanc.

All in all, how would you rate the overall experience of migrating and developing on SCA in general?

It took a total of 50 hours to do, which was good. That includes starting with the diffing of files for changes, to the final bits of testing. Can it be made easier? Migrating any system is difficult, and there's no one single thing that would make the whole process easier.

As I said, the fact that the modules use semantic versioning and are broken up granually really helps. The fact that the entry point files for each module are so accessible really helps. In terms of developer tools, I think we're in a real sweet spot right now.

Thank you for your time!

Thoughts

It was good to talk to Joel because it gave me an idea of what it's like for one of our users to go through something I know that many of you have or are thinking about. I hope you found it useful.

Diffing

The first thing I'm taking away from this is the power of diffs. After he suggested it, I went away ran a diff between Denali and Mont Blanc, it was pretty interesting to see. I've used diffs before, when implementing some functionality a developer has given me to demo, but a whole update? It's a good way to scope out exactly how much work is required, especially when you take into account your overrides.

A basic way to do this is with your terminal and the diff command, but this is quite basic and the diff between releases will be massive. One of the things Joel recommends for this is the Compare Directories feature in WebStorm, a JavaScript IDE that he uses. There are other tools out there too, of course, so find one that you like and make suer you use it.

Version Control

I realise that this isn't something we've talked about on DevSC yet, so I'll look into writing about this soon. In any case, Joel makes a good point: tracking changes is great not only in cases when things go wrong ("who broke the site!?") but it's essential when you work in collaboration with other people.

Joel and his team use Gitflow, which is one way of doing it, but there's a plethora of version control systems and methodologies that you can take advantage of. Any sort of decent version control is helpful, and it'll certainly improve things by providing a detailed history of your site's progression.

Best Practices

The final thing I'm taking from this is the idea that the best way to smooth the road to an migrated site is to put yourself in the best position possible. As Joel said, they had some difficulties early on when they discovered that when they had made overrides, it was difficult to migrate them because they had made wholesale overrides.

This is why we have produced a guide of best practices for customization. It seems trite to say this but preparation can really be the key to success here.

Further Reading