-
Notifications
You must be signed in to change notification settings - Fork 24
I'm upgrading from an earlier version of Mach II to a newer version. Am I going to have any problems?
- Backwards Compatibility
- When Upgrading to a Newer Version
- Core Functionality
- Testing and Staying Current
- Deprecated Elements
- Upgrading
- In Closing
Backwards compatibility is a primary concern when we release new versions of Mach-II, and to date we have not released anything in new versions of the framework that will cause issues with applications running on earlier versions of Mach-II. For example, users have upgraded from version 1.0.10 to version 1.5 and have not had any problems. Unless something out the ordinary exists in your application or you are using something other than what is considered to be Mach-II's public API, you should not experience any problems upgrading.
One of the common upgrade problems people have had is if they have overridden the init() method in listeners, filters, or plugins. Note that it states clearly in the base components for these framework CFCs that you should not override the init() method, and that the configure() method should be used instead, because the init() method is used by the framework and is not intended to be overridden.
Another thing to note is that when you upgrade Mach-II you will need to restart your CFML engine. This is stated in the Mach-II README but is a step that can be overlooked in upgrade situations. The reason the restart is required is because the Mach-II AppLoader is a memory-resident component and is incompatible between versions of the framework, so a simple server restart addresses this issue. Clearing the template cache or reloading your applicaiton is not an acceptable substitute for restarting the CFML engine because the bootstrapper does not instantiate a new AppLoader.
New features and functionality has of course been added throughout Mach-II's history, but the core functional behavior of Mach-II has not changed from version 1.0.10 to version 1.6. The framework authors of course do not have control over how developers write their applications that leverage Mach-II, so in some cases there may be application code that, especially in cases where developers have accessed non-public methods of framework objects, will have issue after an upgrade.
The simplest way to see if your application will run on a newer version of Mach-II is to run the new version of Mach-II on a development or testing server and test your application thoroughly. This step should be taken in all cases of an upgrade because, while we have done our best to ensure backwards compatibility and feel we have succeeded, upgrading directly on a production server is never recommended. Using a functional testing tool such as Selenium can help a great deal with testing your existing application on a new version of Mach-II.
We also recommend upgrading to new versions of Mach-II as they are released, because upgrading from Mach-II version 1.5 to version 1.6 will potentially cause fewer problems than upgrading from version 1.0.10 to version 1.6. Your input also helps us ensure that our releases are more solid and meet your needs better, so we appreciate you testing your applications on new versions of Mach-II as they are released even in the alpha and beta stages.
Note that we have deprecated some aspects of Mach-II, such as resultKey and contentKey, and at some point these elements will actually be removed from Mach-II, so paying attention to deprecated elements and removing them from your code will help make upgrades go more smoothly. You can always see the latest official list of deprecated elements on our wiki.
Also be aware that from time to time we will declare older versions of Mach-II to be "legacy" and will no longer provide support for older versions of the framework other than to tell you that you need to upgrade. We will also only support specific versions of CFML engines with versions of Mach-II. As new versions of the CFML engines are released, we want to take advantage of new functionality in the CFML engines and in some cases it may become more difficult to support older versions of the various CFML engines, so if you are unable to upgrade your CFML engine you may only be able to use an older version of Mach-II. We will give users ample notice when we are going to stop supporting a version of a CFML engine, and for the most part we will follow the "end of life" cycles from the various vendors. For example, since Adobe ColdFusion MX 6.1 is no longer available for purchase or supported by Adobe, we no longer consider CFMX 6.1 as a target platform for the Mach-II framework.
Be sure to look at the common errors you might encounter when upgrading from one version of Mach-II to another. Be sure to read Common Upgrading Errors FAQ before starting your upgrade.
Mach-II is a long-standing, stable framework and the core functionality related to things such as event handling and other key pieces of the framework's functionality has not changed in the past several releases. For planning purposes, we seem to be falling into a release cycle that is approximately annual, so you can expect new versions of Mach-II approximately every year or so. Planning for upgrades in advance and upgrading on development or testing servers as new versions are released will help ensure that your upgrades to newer versions of Mach-II go smoothly.