Migration for non-WiscWeb sites

Preparing for your migration

• Update UW Theme Classic to the latest version.
• Audit your site content
  • Delete any content you no longer need (ideally delete your draft content as well — draft content will migrate).
  • If you have a child theme, remove any customizations you can. Keep in mind that in many cases, CSS customizations are no longer needed because the Block Editor is much more expressive than the Classic Editor.
  • Remove any 3rd-party plugins if possible.
  • In general, simplify your site as much as you can before migrating.
• Purchase an Advanced Custom Fields Pro license if needed. ACF Pro is not bundled in UW Theme 2.0 (it does not use it). If you have a child theme or plugin that will still depend on ACF Pro, you will need to buy a license for it.

Migrating your site

You can see demos of this process in the Distributed Developer UW Theme 2.0 Playlist in Kaltura, specifically Part 3:

1. Change your active theme to UW Theme 2.0, even if your site has a child theme. Otherwise, your site may not load due to PHP errors. Many child themes are set to explicitly check that UW Theme Classic is activated or your child theme may depend on a function or other code provided by UW Theme Classic. (See below for more details on migrating sites with child themes.)
2. Install and activate the UW Theme Blocks plugin.
3. Install and activate the UW People plugin (if your site has people posts using UW Theme Classic’s uw_staff custom post type).
4. Install and activate the UW Theme to Gutenberg Converter plugin.
5. Go to wp-admin > Appearance > Migration Status  and run steps 1 and 2 in the converter.
   • If you had a child theme but will no longer use it, be sure to select the child theme in the first step of the migration. This will move over any menus and customizer options that were previously stored. See below for more information.
6. Review the state of your site.
   •  You may find you need to reassign your Main and Utility menus and footer options.

Reviewing and adjusting migrated page content

Be sure to review the “Helpful resources” section below for more detailed migration review and adjustment.

When reviewing and adjusting migrated content, please note:

• Standard UW Theme Classic pages generally migrate well. Some elements will need rebuilding — e.g. most hero banner content. Other portions of pages may need adjusting using the Block Editor. You may want to replace some migrated content with design patterns or custom blocks provided by UW Theme 2.0. Ideally a site editor and/or designer will take the lead on this review.
• Classic theme text blocks should be converted to blocks: Any Classic Editor WYSIWYG text content should be converted to blocks. These sections will be highlighted on each page. Hovering over one will reveal the Convert to Blocks button. Click that to complete the conversion.

Migrating a site with a child theme

• Every child theme will be different. Some are simple and only exist to override CSS styles. Some add Custom Post Types with their own custom meta fields and backend logic and frontend UI code. Some integrate additional 3rd-party plugins or PHP package dependencies. Some may include direct dependencies on UW Theme Classic code. 
• Audit what your child theme does:
  • If the customization is no longer needed, remove it. Often CSS customizations are no longer needed with UW Theme 2.0 because the Block Editor allows so much more design expression.
  • For customizations you still need, assess whether they have any dependencies on UW Theme Classic code. If not, these customizations may still work — partially or in full — in UW Theme 2.0.
  • You may need to add the Classic Editor plugin and configure it (via settings or in child theme code) to continue allowing editing custom posts with the Classic Editor. It is possible to continue using a child theme with UW Theme 2.0 using hybrid editing experience: the Block Editor for pages and posts and the Classic Editor for custom posts.
  • You may need to rewrite some custom features to make them work with UW Theme 2.0. This will vary from site to site. In some cases you may want to write a custom block. In others, you can sometimes convert classic code to a shortcode and use the Shortcode Block.
• Consider writing migration extensions for custom UW Theme Classic page elements. See the example migration extension plugin and Kaltura playlist for guidance on extending the migration.
• Change your child theme’s style.css file to reference uw-theme-gutenberg as its Template.
• Activate your child theme and then test:
  • Make sure site pages and posts are using the Block Editor experience provided by UW Theme 2.0
  • Test your custom posts types and other custom functionality.
  • If a plugin is causing site errors, deactivate it. Get the site running first. Then assess if your child theme’s code needs updating to work with the plugin and without UW Theme Classic. It’s possible certain plugins may not work with the Block Editor.
  • This is an iterative trial and error process.