WordPress.com VIP Platform
This document is for sites running on our WordPress.com VIP platform.
As part of a migration either to WordPress.com VIP or between two WordPress.com VIP sites, you might need to perform a site merge. Doing so is potentially time-consuming and can produce issues that do not normally occur during a site migration.
What Is a Site Merge? #
A site merge is any time you are migrating more than one WordPress site’s content into a single WordPress site. This could be:
- Two (or more) sites you are intending to collapse into one new site in the course of a migration to WordPress.com VIP
- One site on WordPress.com VIP you are closing and “folding” that content into a parent site on WordPress.com VIP
If you are migrating content and the sources come from more than one posts table, it’s a site merge.
What Makes Site Merges Different from Other Imports? #
When you merge more than one WordPress site into a new or existing single site, you will almost definitely encounter post ID overlap in the two datasets. When the WordPress importer then pulls this data into the eventual target site, the post IDs will be necessarily changed as you cannot have more than one post with the same ID.
Because of this, any connections between posts or solutions that have been created to use post IDs as linking data will need to have that data reassigned or rewritten. Anything that uses post IDs will need to take this into consideration, including:
- Parent/child relationships between posts
- Featured image assignments for posts
- Serialized post ID data stored in postmeta
- Any post ID information used in shortcodes (e.g. the gallery shortcode)
While post IDs are usually the primary concern, this ID confusion can also apply to IDs in other tables, such as term and meta IDs.
Compared to an import that is single-site to single-site, you’ll have additional things to consider before the import begins and as you create your timeline for the migration. Keep these things in mind as you work with the WordPress.com VIP team to create achievable and realistic target dates and expectations. Our advice is to keep things as simple as possible. The more complicated your merge, the more time you’ll need for troubleshooting and QA.
- What is your migration timeline?
- Are you properly allotting enough time to both implement and QA post ID changes that might be necessary due to the merge?
- How many posts and images are you importing overall?
- The greater the number of changes, the longer the additional work for a merge will take to complete.
- Where will you be staging your content? For WordPress.com VIP, it needs to be publicly accessible for us to download images.
- Are you using Co-Authors-Plus on one or both sites?
- Have you looked at author slugs and profiles between the two sites to see how much (if any) overlap you will have?
- You may need to do bulk reassignment of guest author terms to unify the two sets of guest author profiles and attributions.
- If you are merging from a site without Co-Authors-Plus to a site using it (or vice versa), how are you going to integrate that data and make sure your authorship attribution is properly carried forward?
Post Relationships and Custom Features
- Are you utilizing any custom metadata relationships between posts that would encounter trouble if those post IDs were to change?
- A good example of this is custom photo gallery implementations or even the built-in WordPress galleries feature, which depends on post IDs.
- You will need a scripting plan to alter the post metadata as needed to match the new post ID assignments. Remember that you can use the
_original_post_idmeta key to determine which posts have changed and their original IDs.
Publishing Schedules and Site Activity
- With what frequency are posts created on both sites? This will determine the merge timing and how much data will need to be brought forward using a large initial import followed by smaller delta imports. Content fixing will need to be done at each step and will change the timing available. It’s usually best to move as much as possible in the first migrations and then delta-import smaller chunks of content immediately prior to launch.
- Migrations that involve merges will need additional time and effort dedicated to QA. Because these relationships can be altered, you’ll need to come up with a plan for determining a representative sample of posts or other content to check for consistency. It’s best to do this with the initial large import prior to launch to discover and flag and fix any potential data issues.
Who Should Perform the Merge, and When? #
Site merges can and will be performed in different ways depending on the combination of source sites and target sites. Depending on the requirements of the site, it may make more sense for you to perform the merge before the site is moved to WordPress.com VIP at all.
The merge should happen completely prior to moving to WordPress.com VIP if:
- You are merging more than one site to WordPress.com VIP and the merge can be completed prior to your launch on WordPress.com VIP, or
- You are merging more than one site that is no longer active into a site that is also no longer active, whether it is on WordPress.com VIP already or not.
The merge should happen entirely on WordPress.com VIP if:
- You are merging any site into a site that is already live on WordPress.com VIP.
There may be situations where a combination of the two situations is best. Please discuss the merge process with WordPress.com VIP Support for more details.
Starting the Site Merge Process #
As with any import to WordPress.com VIP, please contact WordPress.com VIP Support as much in advance as possible so we are aware of and can schedule resources to assist you with the merge process. Make sure you inform us that the import is going to have merged content.
We request that you prepare a local development environment on which you can partially test the merge to look for potential problems and identify scripting needs you’ll need to address. We’ll happily provide you with partial exports for the sites you plan to merge so you can do a test run and identify problems before they occur during an actual import. Remember that imports to a live site are much more difficult to reverse; the more we can help you identify problems ahead of time, the more efficiently and error-free the eventual import and merge will be.
Making Site Merges Successful #
We’ll need you and your developers to contribute code for many types of merges, usually in the form of wp-cli commands. When you contact us, we’ll send you a questionnaire to make sure we’re considering all of the factors necessary to ensure your merge is successful.
When you merge to a site on WordPress.com VIP, we’ll take care of:
- Fixing featured images,
- Remapping image URLs in post content,
- Providing useful import origin meta to help you in fixing problems after the fact,
- Fixing post parent/child relationships, and
- Fixing duplicate Guest Authors in Co-Authors Plus that might have been created.
You and your development team will need to:
- Identify any postmeta or shortcode usages in your site content that will be disrupted by a site merge,
- Create and test any CLI scripts that will be needed to repair these relationships,
- Commit any needed CLI scripts to your theme, inform us of them and their purpose, and provide us with instructions for executing them at the proper time,
- Create any scripts needed for term mapping (or perform that prior to the import itself), and
- Test any merges with sample data to identify potential issues prior to scheduling the site merge import(s).
If you have any questions, please don’t hesitate to contact WordPress.com VIP Support.