Package updates (migrations)

After a new version of a package is released, websites that have the old version installed will be updated.

Misconceptions

Let’s clarify a couple of misconceptions you may believe about package updates that are incorrect.

All updates to a package are installed one after the other.

Incorrect: all historic versions are updated straight to the latest version.

All websites will be updated automatically.

Incorrect: updates may be disabled on a per-website basis.

If I have a package that is only used on a single website by a single user and I know that website was updated from version A to B, then there will be no updates in the future from version A to B (or to later versions).

Incorrect: a historic version of the website may be restored later and the package updated again.

Key ideas to understand

Once a package is released with certain apps, users will create instances of those apps. As you release new versions of the package, you will have to assume it forever that old apps are still used by instances out there. Those instances will be updated so your package should be prepared to handle that. (Remember that historic versions of websites will also be restored and updated.)

This is not as hard as it may sound at first.

1) Define the schema used by every app (what attributes and children their instances may have) and make sure to never change that. You can change the application logic as long as it doesn’t affect the data stored in instances.

2) If you have to change what data is stored in individual instances, create a new version of the app instead (within the same package). After that, create an update script in an .Update file within the app, that will update all instances and migrate the old data structures to the one used by the new version of the app. (Note: the new version of the app is in fact a new app.)

3) Do not remove, move, or rename old apps. Do not change their file IDs either. Files reference associated apps by their file types, which store file paths. For this reason, apps must retain their file paths. Because of this, you will find packages store applications at paths like /apps/gallery/v1. That way, new versions will be stored next to v1 with increasing version numbers.

We will most likely be moving to using file IDs instead of file paths for file type references, so make sure to keep the file IDs unchanged as well. Once and if we do that, we will be able to move the apps around within the packages as long as their file IDs do not change.

File IDs are paths too
Note that file IDs are not simple numbers. Boomla does have a numeric ID for each file, but only within a volume and it is called a file node ID. To identify files within nested volumes, we have to use nested file node IDs, called file IDs.

Updating app instances

See the .Update method docs.

Updating package data stores

Package data stores that are stored under /sys/packageData/PACKAGE_NAME are regular app instances. They have a file type and thus an associated app. Upon updating the package, if the associated app implements the .Update method, it will be executed.