In bug 962913, the idea of 'profile extracts' were implemented to allow developers to test profile upgrade situations in gaia integration tests. This feature needs documentation so that developers can learn how to make the system run an upgrade in order for their test to work.

Just storing some notes here on how upgrades happen. Any references to coreAppsDir usually resolves to the profile directory, by way of b2g/components/DirectoryProvider.js dom/apps/AppUtils.jsm:isFirstRun is the function that checks to see whether we're upgrading or on our first run. We need to be able to trip this to return true on integration tests that require profile upgrades. dom/apps/Webapps.jsm:installSystemApps is the function that gaia uses to either install or upgrade core apps. On upgrade, it loads the old apps registry, removes old apps, and performs installation of new apps.

Ok, first assumption in Comment #1 is wrong. On DESKTOP, coreAppsDir resolves to the profile directory, as the comment in DirectoryProvider.js says. On the phone, coreAppsDir resolves to /system/b2g/webapps, which is a pristine copy of the certified apps, with their own webapps.json. The user's webapps.json are in /data/local/b2g/webapps. That's how we avoid overwriting on upgrades. Currently, there's no mechanism to replicate this on desktop, we just assume we always completely overwrite the profile directory. We should instrument the DirectoryProvider via prefs in order to change how this works and properly emulate upgrades.

Due to bug 1001757 landing, we don't really need extracts anymore.