How to upgrade /apps overlays out-of-the-box source files

Objective

When upgrading AEM, most customizations that are overlaid from /libs folder to /apps might not work after upgrade. Those customizations might even break out of the box functionality after upgrading. To solve this situation we follow the steps below to migrate our customizations to the newer version of AEM.

Steps

On your current (non-upgraded) AEM environment, go to http://aem-host:port/crx/packmgr/index.jsp and log in as an administrative user

Create a package containing all your overlays under /apps folder and the corresponding /libs files. For example, if you have overlaid /libs/cq/ui/widgets/source/widgets/wcm/SiteAdmin.Actions.js under /apps/cq/ui/widgets/source/widgets/wcm/SiteAdmin.Actions.js then you would include both of those paths in the package.

Download the package

Unzip the contents of the package locally

Download a diff tool on your machine. On Windows you can use WinMerge and on Mac or Linux you can use KDiff3.

Install the diff tool

Use the diff tool to diff the jcr_root/apps and the jcr_root/libs folder extracted from the zip in step 4

Use this diff to review your old customizations you had made when overlaying the out of the box files

On your local machine, install a clean instance of the version of AEM you intend to upgrade to

Go to http://aem-host:port/crx/packmgr/index.jsp on the new instance

Create a package of your same overlay /libs locations from the newer version of AEM

Download the package

Unzip the contents of the package

Use the diff and the files extracted from the newer AEM version to "upgrade" or re-implement your customizations