Write Migration Guide

[samus-aran]

Page with Issue

New Page/Structure.

The goal here is to provide users/developers a easy to follow guide on how to upgrade their customised instance with a large version gap. The particular scenario I had in mind is 7.8.x -> 7.10.x.

Obviously we would not be able to get all the use cases and each business providing SuiteCRM services have their own process but the aim here is to help our community with a general 'watch out' or 'how to' on how to identifying conflicts i.e. did they do core changes (yikes!), areas of major changes i.e. themes, general guidance on how to take a back up, test on a UAT instance and regression testing.

I'm certain we can all share our knowledge of particular scenarios at a high level that would help other developers on how they approach these particular problem areas and even enlighten a few of us veterans 😉

I suggest we discuss this here in comments on what we want to include before whipping up a starting page.

What is wrong, less clear, or missing

There isn't a clear enough migration guide.

Proposed fixes and/or additions

The Maintainers, Partners & Anyone with migration experience share your thoughts or even ideas on how to structure this and if anyone would like to take on certain areas.

[connorshea]

I've described the system we have a few times, but I'll repeat it here. I don't know how/if this'd fit in the migration guide, but I figured I'd bring it up since it's worked quite well for us.

---

We implemented a system where if we modify any core files we mark the changes with a big comment block that explains the change and links to any relevant issues/PRs/commits.

/**
 * CUSTOMIZATION NOTE
 * The change in this file was backported from 7.10.7, see <GitHub commit link> for more info.
 * We can use the upstream file once we've upgraded to 7.10.7+
 */
Code->goesHere()
/**
 * END CUSTOMIZATION NOTE
 */

This made the upgrade process for 7.9.17-to-7.10.15 – where I go through each changed file that we've customized and determine whether the upgraded file needs to be modified to preserve any of our customizations – a lot faster. Only took maybe 4-5 hours of work, compared to multiple days of tedious work when upgrading from 7.9.4-to-7.9.17 before this system was in place.

---

This system has a couple of benefits:

• It's clear what changes from the upstream can safely be merged into our 'fork'
• It's clear what changes need extra work and proper conflict resolution
• It helps us clean up backports after we're on the version they were backported from

[pribeiro42]

To me, the most effective way of doing such migrations is to set up a git repository, then we can easily check the changes, conflicts and whatever...
It's very easy to do a git rebase and check if you need to update any customizations you've done...

[pgorod]

It's very easy to do a git rebase and check if you need to update any customizations you've done...

Can you please explain this a little better?

[pribeiro42]

Sure, lets say you have a copy of the suiteCRM github repository. In that repository you create a branch for your customizations:
git checkout -b my_custom_stuff

You change a few files, and then a new version of SuiteCRM is released. So, you switch to the main branch (lets say its master):
git checkout master
pull in the new version:
git pull origin master
then you change to your branch:
git checkout my_custom_stuff
and try to rebase it against the new master:
git rebase master

If you had changed any of the core files, a message is displayed and the rebasing interrupted to allow you to check what changes need to be done, modify the files and so on...
This situation can occur more than once, and each time you have the option of modifying the files and commit the changes, or abort the rebase and get back to the starting point.
After you apply those changes, you can continue with the rebase process.. In the end you have your customizations applied on top of the new suiteCRM version...

Hope this all makes sense to you... :)