Upgrade from 12.0 Beta to the latest 12.0 GA

If you have started developing a new Hippo project based on version 12.0 Beta of the Hippo project archetype, there are a few actions necessary to upgrade your project to the 12.0 GA version. These actions are primarily triggered by refinements of CMS 12's repository data categorization mechanism, and the forthcoming changes to the archetype and the auto-export mechanism. For inspiration and reference, we recommend to generate and keep at hand a fresh, empty Hippo project from the latest 12.0 GA archetype (12.0.2 or later).

Update the project files

First and foremost, you should update your project's root pom.xml to use the latest 12.0.x version of your <parent>. Also, update the <essentials.version> property to use the latest 4.0.x version of Essentials.

Rename repository-data submodules

In order to better reflect their intent, we renamed the config and content submodules of the repository-data module to application and development respectively. Since the CMS 12 documentation refers to these modules by their new name, we recommend that you update your project's structure to reflect them. This renaming should be reflected in

1. The modules' name
2. The modules' Maven artifact ID
3. The CMS module's dependency on the application module
4. The cargo.run profile's configuration for deploying the development module locally, including the without-content profile
5. The distribution configuration for building a distribution including the development module, under src/main/assembly, including the corresponding dist-with-content profile
6. The (sub)module name in the hcm-module.yaml definition files within the repository-data application, development and webfiles submodules
7. The autoexport:modules property definition in the application submodule autoexport-module.yaml and development submodule main.yaml files. See also for reference the general (updated) AutoExport Add-on documentation.

When in doubt, refer to the fresh 12.0 GA Hippo project.

Drop dependency on webfiles from repository-data application submodule

Due to less stringent checking by the Auto Export Add-on, version 12.0.1's dependency of the repository-data/application module on the repository-data/webfiles module, expressed through the after property in the module's src/main/resources/hcm-module.yaml file, is no longer necessary. We recommend to remove that dependency, if your project has it. The module part of that file can just be module: <module name>.

Remove build number plugin from repository-data submodules

From the install build configuration of repository-data/application/pom.xml and repository-data/development/pom.xml, remove the buildnumber-maven-plugin plugin (leaving only the JAR plugin).

Improve categorization for HST

Since CMS 12.0.0, we have improved the categorization into config and content for HST data. In order to make your project consider the part of the HST presentation which is managed by CMS users (webmaster role) as content, while the part managed by the project developers is categorized as config, the following refinements should be applied to your Beta project:

1. Extract any child node of nodes of type hst:channel located under an hst:workspace node into a separate Content YAML Source under /repository-data/application/src/main/resources/hcm-content. At the same time, decorate the hst:channel node with .meta:residual-child-node-category: content.
2. Do the same for any nodes of type hst:containercomponent, hst:sitemenu, hst:pages and hst:sitemap which are located under an hst:workspace node.
3. In /repository-data/application/src/main/resources/hcm-config/hst/hosts.yaml, decorate the /hst:hst/hst:hosts node with .meta:residual-child-node-category: content.
4. Below this node, make sure that all nodes of type hst:virtualhostgroup, hst:virtualhost and hst:mount have that same decoration.
5. In order to have above decorations sprinkled in automatically by auto-export, update the auto-export configuration according to the latest settings provided by the latest 12.0.x archetype at /repository-data/application/src/main/resources/hcm-config/configuration/modules/autoexport-module.yaml

Remove hst:hosts and hst:sites root nodes

As of version 12.0 GA, the nodes /hst:hst/hst:hosts and /hst:hst/hst:sites are provided by the product. They therefore no longer need to be defined in the project's repository data definitions. Keeping them there will trigger warning log messages from the configuration management mechanism. To remove them from you project, remove the following 3 property definitions of the /hst:hst/hst:hosts node from /repository-data/application/src/main/resources/hcm-config/hst/hosts.yaml:

    .meta:residual-child-node-category: content
    jcr:primaryType: hst:virtualhosts
    hst:defaultcontextpath: /site

Also, remove the following 2 property definitions of the /hst:hst/hst:sites node from /repository-data/application/src/main/resources/hcm-config/hst/sites.yaml:

    .meta:residual-child-node-category: content
    jcr:primaryType: hst:sites

Improve root folders for documents and images

The project's primary root folders for storing documents and images are located at /content/documents/[project name] and /content/gallery/[project name] respectively. In CMS 12.0.0, they were bootstrapped by the /repository-data/content module. As of the 12.0 GA version, we recommend to bootstrap them from the /repository-data/application module. For this end, the corresponding YAML Content Sources should be moved into the desired module. Also, in order to see nice names in the CMS Content perspective for these folders, on these two nodes, you should add the value hippo:named to the jcr:mixinTypes property, and add the hippo:name property to specify the nice name of your project. Again, for inspiration, see the latest 12.0 GA archetype at /repository-data/application/src/main/resources/hcm-content/content/documents/[project name].yaml.

Move the author and editor test users into the development module

The archetype provides you with test users for the author and editor role. In order to avoid that these users are bootstrapped into a production environment, they should be moved from the application module into the development module. You can do this as follows:

1. Move the files user-author.yaml and user-editor.yaml from /repository-data/application/src/main/resources/hcm-config/security/ to the corresponding directory in the /repository-data/development module.
2. Move the group membership of these authors, defined in the file src/main/resources/hcm-config/main.yaml from the repository-data/application to the repository-data/development module. Include the membership of the editor in the webmaster group in this move.
3. In order to avoid that accidental changes to these users' passwords get exported into your project sources, mark the password fields of both users to fall into the system category:

   hipposys:password:
     .meta:category: system
     value: <desired password>
   hipposys:passwordlastmodified:
     .meta:category: system
   hipposys:previouspasswords:
     .meta:category: system
   

Update distribution configuration

If you intend to deploy your project's /repository-data/development module to non-local environments (in order to bootstrap the module's config and content definitions), the archetype provides you with the dist-with-development-data profile to create a distribution that includes said artifact. In CMS 12.0.0, the configuration to create this distribution was incorrect. To fix this, edit /src/main/assembly/shared-lib-development-data-component.xml and replace both occurrences of "bootstrap" with "repository-data" in the value of the <source> tag.

Also, version 12.0 GA no longer includes the hippo-configuration-management-api artifact in the shared/lib. Therefore, we recommend to remove the corresponding line from the file shared-lib-component.xml.