Best practice for conducting a Magento update? [closed]

Question

What is the best practice for making a Magento update (of a badly maintained Magento installation).

I think of things like the following:

• Have a look at full overwrites modules in app/code/local - compare the files with the old version and forward-port them to the new Magento version
• Compare templates
• Compare layout XML files (if they were copied directly to the custom theme folder and no single layout.xml containing only the real updates was used)
• Compare the methods of the rewritten classes to the methods of the original class

The main problem is: When diffing files in old, badly maintained Magento installations, you never know, which version the original file that was copied had. Sometimes I tried to identify the old version by having a look on Magento's copyright in the file comment.

To avoid hassle during update we usually do the following:

• Avoid rewrites, use events instead
• If rewrites are necessary, try to not copy code but call parent::method() to keep only the necessary functionality in the overwritten class
• If copying code is necessary, use a marker-comment such as [Mycompany BEGIN] ... [Mycompany END]
• Do not copy entire layout files but use a single layout.xml that does only updates.

But how to do an update if those precautions where not taken?

Answer 1

As others have noted the key here is to make it comparable against clean installation so here's what I would do with the help of version control.

1. get yourself the clean version of Magento you are currently on and don't forget to make it comparable. Or use a existing git mirror of magento (see more http://blog.speedupmate.com/post/4063307705/magento-git-mirror )

2. set up a master repo based on 1. here and have it at hand

   Asked in comments: Your ultimate goal is to have a clean core with all files in git that are present in magento installation files. That is needed so you can compare everything against the clean installation. Managing core changes, core filetree (existing, non-existing, added files). You can handle your exceptions with .gitignore (excluding media , cache, all fiels with server specific scope local.xml .htaccess). I find it easy to move out Magento core files to different (non public) directory (as explained here http://blog.speedupmate.com/post/9992573819/poor-mans-multisite-setup-for-magento ) and that will give me a code state where .htaccess never conflicts on upgrade. I also never include media in version control , cache and all temporary files that magento generates. This will guarantee you clear path on upgrades as you can disable all for the upgrade time. Comparing the code later will give you scope of things you need to overview and you can estimate how long it will take you to compare the changed parts and go live with upgrade.

3. now with your existing site and git config in place (to make it comparable) do a git init on your codebase and add everything to git there , this will go over your git config and make every file comparable (same newlines, whitespaces etc) then fix file permissions to be the same. After that you can remove the .git folder from your site as you only used git to make files comparable there.

   Asked in comments: The point here is to have git do work for you like converting all line endings to unix style and ignore whitespaces, you can ignore permissions too in theory but that's not useful (formatting is bit off here so \ represents a line break between commands

   git config core.autocrlf input \ git config core.eol lf \ git config apply.whitespace nowarn

   Now if you do git init and add those configs and add everything to git then during committing stage git will replace all your windows line endings and all that crap to unified and comparable style. Note that zend coding standard suggest unix style line endings however you will also see the files where Zend library does not follow it's own standards. Key point here is that you need your files to be comparable to minimize the diff load you have to do. You will remove the .git folder after git has formatted all your bad installation files for you. Git is only used to automate the "make things comparable process" in this step and nothing else

4. checkout your test repository based from your master repo in 1. and checkout a branch with the version you are currently on and name it "testsomething" or whatever you need

5. delete everything from that checkout folder and leave only .git in place so it is empty but version control still exists there. It will be in state like everything is deleted and this is important here cause based on that you will know what files you might have deleted on your bad site.

   Asked in comments: I usually add whitespace ignoring to git config (local or global scope is available) and let git handle that for me. When working in teams we always agree on based Zend standards: 4 spaces for tabs, unix style line endings and git config variables mentioned at 3. and if build scripts are involved we do code formatting and validation with commit hooks.

6. move in all files to your empty dir (note that you have removed the .git dir from your existing site after making it comparable) from your fcked up magento installation (they are comparable now) and run a git status > changes.txt . This file now lists every difference you have , any new file you have, any deleted, renamed, etc file you have on your "fcked up installation" against the clean Magento code that you are currently on.

   Explaining based on comments: I usually do git status --porcelain

7. have a .gitignore file in place to help you discard local.xml var/* or every file/dir that you don't need to version control and also .DS_Store, .Thumbs.db and your ide created project files from git. YOu don't need all Media and cached files and files that are different in each server on your version control.

From there you should overview that list carefully and based on that list you should:

• move every core change to app/code/local/ and checkout the changed file to it's original state (keep the copied one and discard the changes in core with git checkout filename)
• move every changed core template and layout file to your own theme folder and checkout the changed file to it's original state
• revert or migrate .htaccess changes or decide if you need to preserve or discard

Now you still are in bad shape but you are now:

• based on clean core
• based on versioned master tree in a separate branch

Now you can benefit on being version controlled, comparable and in separate branch based on your master branch that has mergable versions of Magento in it. So lets try to upgrade, here's the key points of 100% success on doing this.

1. first step would be disable all the "crap" that you have now separated to app/code/local/Mage/ and to separate theme. If your core is clear and themes can be disabled you have no custom code interfering with upgrade process. So go ahead disable:

   • all local extensions and custom community extensions by moving them out of app/etc/modules/ to temp folder let it be app/etc/inactive/
   • disable custom themes and turn on base/default/
   • this is your benefit on being in comparable state. You know what's different and you can disable that and diagnose things based on that

2. now if you have all major versions in the master tree in your repo tagged or branched separately then getting the version higher is just a command away: git merge "magento-vhateverthenextversionis"

   • again after doing this "git status > changes.txt" will give you a list of all changed files between your versions
   • executing the site on browser will perform the upgrade and since you are on default theme and no customisations activated it will perform like a charm
   • repeat the upgrade version by version and save your code state by tagging in your test branch or create a new branch for each version based on existing testing branch , this way you have saved clean state for every magento version you have upgraded in between
   • again the extra bonus here is that if you do it with version control you also will get rid of the files that new versions discard and you can delete them easily

3. if you have iterated the 2. to your desired magento version to latest then it is time to eat the "s*it" that you have inherited and do following:

   • analyse all extensions you have and see if they can be upgraded, if you can upgrade and turn on see if they work with default theme
   • diff each core rewrite in app/code/local/Mage against it's original version in new form from app/code/core/Mage. You can use diff tools like winmerge.org or changes (whatever os and tool you prefer) one by one or diffing whole folders
   • same goes with your template and overwritten templates or layouts. COmpare to original and merge your changes to new base template and get rid from old DOM
   • turn on theme changes and extensions one by one and debug

4. if you get to this point then you have done a shitload of work , dependant how messed up the installation is it can take days. But hey now you have a clean magento core that is version controlled, separated overwrites that are merged and overviewed , and all stuff in separate theme that can be disabled.

5. fun part is that if next upgrade of magento is available you can whistle and add it as comparable to your master tree and merge down the changes, know what is changed and have a clear scope on what to overview and test.