Plugin Upgrade and Version Compatibility

Compatibility is only considered in files fomr the pure plugin release, that is the package without samples inside. Sample files will change in any possible condition.

File Compatibility

The plugin has two folders as described in Assets Introduction. EasyAR folder and files in Plugins folder in the release package are internal resources which will change without notification between releases.

Although EasyAR Sense Unity Plugin is released in source, it does not offer file level compatibility between versions. You should treat the EasyAR Sense Unity Plugin like a bunch of “DLLs” with dependencies to each other.

EasyAR Sense Compatibility

EasyAR Sense Unity Plugin has EasyAR Sense inside. The plugin is guaranteed to work only with the EasyAR Sense released within the same package. In some rare cases, when the EasyAR Sense Unity Plugin package does not change much between releases, the EasyAR Sense can also be switched. In this case, the EasyAR Sense libraries in Plugins folder could only work with the csapi file in EasyAR/Scripts folder within the same EasyAR Sense release. EasyAR does not offer this kind of compatibility by design, so you have to check it by your own and at your own rist in case you need.

Interface Compatibility

Interface compatibilities are only guaranteed within a minor version. Huge interface changes will be noticed in the release notes.

Upgrade Guide

The only clean way to do an upgrade is to remove the EasyAR folder and all EasyAR libraries and configuration files in Plugins folder completely (do not forget .meta files if you are doing this in system file managers) and import new files after that. An import of the new package on existing projects will fail in most cases because Unity do not handle removed files. This rule also applies to 1.x, 2.x and 3.0 versions of EasyAR Sense Unity Plugin.

Here are some steps of doing clean upgrade,

  1. Backup the whole project or checkout a clean workspace in version control system if you are not sure about what will happen.

  2. Remove EasyAR folder and all EasyAR staffs in Plugins folder.

  3. Import new plugin package.

  4. Check compile errors and fix them, change the way of API calling or use alternatives when interface changes.

  5. Check objects containing EasyAR resources in the scene, check if any references are lost and if any values have been changed unexpectedly.

  6. Check release notes and plugin interfaces about other changes if possible.

  7. When there is a huge design change in the plugin like upgrade from 2.0 to 3.0 or 4.0/3.1, you need to check every code and scene objects that use EasyAR features, and check the new samples to learn what have changed.

The above steps are suggestions more than rules.

It is not a good choice to change any files in EasyAR folder. You will find another way to reach the same result in most of the case. If there are really any reason to do that, you should keep that change as small as possible and make changes clear enough to find in another day. Keep changes in separate patch files which applies when build or repository setup would be a good practice. When it comes to an upgrade, try strip out the code and reapply patches after a clean upgrade. If you consider your changes are common feature request, please contact us and we would consider adding them into later releases.

If you are not in the condition of doing a clean upgrade, the safest way would be a complete compare of your project and the new package imported into an empty project and do manual merge. Comparing your projects with the old package would also help to let you know which file has changed and which not.