A 10-step guide for upgrading Drupal 7 to Drupal 10

About migrating from Drupal 7 to Drupal 10

Official support and security updates for Drupal 7 will end on 1 November 2023. It's important to upgrade to a more secure and updated Drupal version, like Drupal 10, before the deadline arrives — or investigate other potential options. Find out more about Drupal 7 End-of-Life

In this post, we'll give you a 10-step guide to upgrade from Drupal 7 to Drupal 10.

The high-level steps are:

• Step 1: Assess your current Drupal 7 site
• Step 2: Plan your upgrade path from Drupal 7 to Drupal 10
• Step 3: Evaluate your current modules
• Step 4: Create Drupal 10 site with contributed modules
• Step 5: Upgrade your custom modules
• Step 6: Migrate your data
• Step 7: Rebuild your theme or build a new theme
• Step 8: Test your site
• Step 9: Launch your Drupal 10 site
• Step 10: Train your team on your new Drupal 10 site

Salsa can also help you along the way. We offer a range of Drupal 7 End-of-Life services including two innovative options that may mean you don’t need to upgrade to Drupal 10 at all, which could save you time and money! These two options are:

• Leave it — Leave Drupal altogether by creating a static copy of your website with no CMS to manage or maintain

• Keep it — Keep your Drupal 7 website past the End-of-Life deadline (without security risks) by creating a static copy of your website for the public, and a locked-down Drupal 7 environment for your content editors

Salsa’s other innovative End-of-Life service is for clients who want to move to Drupal 10 but without the hefty price tag or lengthy ground-up site design and development stages. We can rebuild your new Drupal 10 site with CivicTheme, a modern design system and Drupal 10 theme. This option saves you serious time and serious money. It’s the fastest, easiest and most cost-effective way to get onto Drupal 10. More about Salsa’s End-of-Life options.

Preparing for your project

Before you begin, you’ll want to have a team for your upgrade project, which typically would include a project manager, one or more Drupal developers and quality assurance (QA) testers, and the necessary business stakeholders to make key decisions and approvals. These can all be internal staff or some can be external specialists to help you through your project.

You’ll also want to track your progress and key decisions using whatever tools you’re comfortable with such as Jira, Google Docs, etc. It’s particularly important to note any changes and removals that are approved by your team so you can refer to them later as needed.

Before you jump into your project, you should also get familiar with Drupal 10 and its features by installing it in a development area where your team can familiarise themselves and experiment. This will help you decide what changes you want to do during the upgrade.

So, let's begin our 10-step guide to upgrade your website from Drupal 7 to Drupal 10.

Step 1: Assess your current Drupal 7 site

The first step to upgrade from Drupal 7 to Drupal 10 is to assess your current Drupal 7 site.

Upgrading from Drupal 7 to Drupal 10 is really a complete site rebuild. This means it’s a good time to update your design, content, information architecture (IA) and features. If you’ll be changing features, those need to be understood before and during module evaluation (step 3). If you’ll be changing your content structure or IA, these need to be understood before the data migration in step 6. If you’re changing your design, the designs will need to be finished before step 7.

Here are some key tasks to complete during this step:

• Review your current site and make a list of all the content, features and functionality

• Evaluate your current content and functionality, thinking about what you want to carry over to the new site as-is, what you want to change and what you can ditch

• Review your current design/theme and decide if you want a new look-and-feel — if you redesign your site, you’ll need to add a design phase into your project plan

• Identify any potential issues that may arise during the upgrade, such as custom modules that aren’t compatible with Drupal 10

• Make sure your hosting environment supports Drupal 10

Step 2: Plan your upgrade path from Drupal 7 to Drupal 10

Before you dive into a Drupal 7 to Drupal 10 upgrade, remember that in some cases, you may decide NOT to upgrade to Drupal 10 (see options 3 and 4 below). Consider all your options carefully and choose the approach that's best for your needs.

Salsa’s End-of-Life services include:

1. A traditional upgrade/rebuild from Drupal 7 to Drupal 10 with an existing design system or new bespoke design theme and /or design system, including a design phase, development cycles, testing and deployment

2. A streamlined and innovative upgrade/rebuild from Drupal 7 to Drupal 10 using a modern, open source low-code design system with a rich library of pre-built feature components and Drupal 10 theme, CivicTheme (this option gets you onto Drupal 10 for significantly less money and less time with its out-of-the-box, ready-to-use components)

3. Creating a static copy of your website so you don’t rely on Drupal anymore at all (leave Drupal quickly and easily and remove the need for any content management system (CMS) at all)

4. Creating a static copy of your site for your public site visitors, while keeping a locked-down version of your Drupal 7 site just for your content editors to manage content changes (so you can keep Drupal 7 but without the exposure to public traffic and security risks)

No matter which option you choose, be sure to set a realistic timeline for the upgrade process. Option 1 will take the longest (by far) and the timeline varies significantly depending on your site’s size and features. Options 2-4 will generally take between 2-8 weeks, depending on your site's size and complexity.

If you think option 3 or 4 sounds like a good fit for you, you can either get a quote or chat with us about how to maintain your current Drupal 7 site without upgrading to Drupal 10.

But if you’re still interested in upgrading from Drupal 7 to 10, read on and let's get planning!

Step 3: Evaluate your modules

Modules are essential components of your site's functionality, and it's important to make sure they’re compatible with Drupal 10 before you upgrade. Also, Drupal has evolved a lot since Drupal 7 so it’s good to understand the current best practices and use those when choosing your Drupal 10 modules. Just because there’s a Drupal-10-compatible version of one of your modules, doesn’t mean you should use it — there may be a better way to add that functionality now.

Here are some key things to keep in mind as you evaluate your modules:

• Determine what core module features you’re using in Drupal 7 that are no longer available in Drupal 10 and what can replace these

• Review your contributed modules’ compatibility with Drupal 10 by reviewing each module’s page on drupal.org

• Check for updated versions of your modules that support Drupal 10 and, if a Drupal 10 version is not currently available, check the module’s issue queue for a patch (the Upgrade Status module makes this easier)

• Check the status of your modules to see if they’re still being supported by their maintainers

• Consider alternative modules that offer similar functionality and are compatible with Drupal 10 — these may be more supported than what you’re using

• Decide which modules are essential for your site and prioritise these for updates or replacements — now is the best time to remove features that you no longer need or that aren’t used very much

• Make a list of any custom modules — these will need to be rebuilt in Drupal 10, replaced with core or contributed modules, or removed altogether

Step 4: Create Drupal 10 site with contributed modules

Going from Drupal 7 to Drupal 10 is a migration. This means you build a new Drupal 10 site and migrate the content from your Drupal 7 site to your new Drupal 10 site. You’ll need to create a fresh Drupal 10 site to add your modules and content structures. Make sure to use the latest available version of Drupal 10.

From your evaluation, you should have a list of Drupal 10 modules that you want to add to your site. Install and configure these on your Drupal 10 site. Have your team test the site and your stakeholders sign off on any new or changed functionality. Make sure not to add any modules that your team has decided are no longer needed.

You’ll also need to create the content structures you need for the migration including content types, block types, vocabularies, media types, menus, etc. Note that your content architecture in Drupal 7 likely will not make sense to replicate exactly in Drupal 10. Follow the current best practices. This is the best time to rework the structure of your pages, add or remove fields and leverage new features like Layout Builder. Make sure you don’t add any content types, vocabularies, fields, etc. that have been approved for removal.

Step 5: Upgrade your custom modules

The next step is to upgrade your custom modules. Here are some key things to keep in mind:

• Understand Drupal 10 best practices and what can be done with core and contributed modules so as to minimise custom code

• Remove any functionality you can so there is less code to rewrite

• Try to rationalise custom modules as much as possible — custom modules should be used sparingly (read our blog on Best practices for custom requirements)

• Once you’ve got your ‘must-have’ list, update the custom modules so they’re compatible with Drupal 10 — this typically involves rewriting your code and using new APIs provided by Drupal 10

• Test the functionality provided by your custom modules and get business stakeholder signoff for any changes

Step 6: Migrate your data

Migrating your data is a critical step during the upgrade process. For small sites, you can “manually migrate” (copy and paste) content between sites but for larger sites this should be automated. Review the official Drupal.org documentation for automated migrations. You can also use open source automated migration tools like Merlin. Merlin starts with a smart spider that helps to find all public-facing content on a website. Based on a set of defined rules these URLs are separated into categories of content (e.g. news articles vs blogs vs staff profiles). These pages are then interrogated and broken down at a field level (e.g. title, publish date, body, file attachments, etc.) and output into a generic, machine-readable format (JSON) — ready for ingestion into a CMS or other platform.

Before the migration, you’ll need to have the correct content structures in place in Drupal 10 for the data to be migrated into. This will include content types, vocabularies, media types, menus, etc.

Here are some key things to keep in mind as you migrate your data:

• It’s essential to perform an audit across content pages, images, files and other data

• Delete and clean up content, images, files and other data on your Drupal 7 site before the migration — this gives you a cleaner ‘base’ to start the migration process from

• Make sure your Drupal 7 site core version is the latest available

• Back up your data in case anything goes wrong during the migration process — ideally, have an automated backup schedule in place for both the Drupal 7 and the Drupal 10 sites

• Freeze content changes on the Drupal 7 site during migrations

• Depending on your site’s features, you may also have site configuration that needs migration that must be handled according to the module’s specifications

• If you’ve removed content or changed their paths, make sure there are redirects from the old URLs to someplace appropriate on the site to prevent 404 errors

• Test your Drupal 10 site to make sure the content and data has all come across as expected

• Keep in mind non-technical team members may not be able to properly review the site content yet because it is not yet themed

Step 7: Rebuild your theme or build a new theme

The next step is to rebuild your theme. Note: We often run our migration stream in parallel to both the backend build and the theme work. But for the purposes of this article, we’re creating a more sequential process.

Here are some key things to keep in mind as you rebuild or build your theme:

• Choose the best approach — you could rebuild your old theme, create a custom theme from scratch from new designs or use an existing Drupal 10 theme like CivicTheme to streamline the process

• Because Drupal 10 is so different to Drupal 7, now is the best time to do any redesigns or switch to a design system

• If redesigning, get business stakeholder signoff on all designs prior to creating or configuring your Drupal 10 theme

• Keep in mind any IA and content structure changes

• Test your theme to make sure everything is working

• Non-technical team members will have an easier time reviewing the site’s content once the updated theme is in place

Step 8: Test your site

Most of your testing (QA) work should be done methodically so you’re testing individual components. Ideally, you should track each item to test in tickets, which would cover:

• Frontend tickets — what the user sees on the site (your theme)

• Backend tickets — what the content editors and site admins can see/do

• Migration tickets — the content, images, files and data you’re migrating from Drupal 7 to Drupal 10

Testing/QA work should be done on different devices and browsers to make sure everyone can use your site. You should also test site performance and accessibility.

Once the site has been carefully tested by technical and QA team members, get business stakeholder approval as needed. Remember to keep in mind the approved list of removed and changed features.

Note: We find it’s better to include web accessibility into the project lifecycle early on, so designs are reviewed for accessibility compliance and every frontend ticket includes the required accessibility acceptance criteria.

Step 9: Launch your new Drupal 10 site

You're almost there! Here are some of the things to do to launch your new site:

• Choose a launch date

• Tell your users

• Freeze content updates and admin use of your Drupal 7 site

• Run any final incremental data migrations as needed

• Switch your DNS to point to the new site

• Click around the Drupal 10 site after launch and try with different devices, to make sure everything is working

• Check your logs for any missing pages (404s) and other warnings and errors

• Re-add any redirects and vanity URLs you may have been using on the old site

• Restrict access to Drupal 7 site

• Celebrate your success: You did it!

Note: Once you’re sure you no longer need the Drupal 7 site, you can create a static snapshot and a full backup for archival. Test the backup to make sure you’re able to install it in case it needs to be revived for reference.

Step 10: Train your team on your new Drupal 10 site

Finally, with your site launched you’ll need to train your team on the features and functionality of your new Drupal 10 website.

Note: If you’re upgrading your Drupal 7 site to Drupal 10 using in-house team members or you’re loading new content, you’ll need to train people earlier.

Salsa provides content training with many of our site builds and we’re also the official training providers for the whole-of-government CMS system GovCMS (Drupal), running both content admin course and site builder course.

Don’t forget to maintain your Drupal 10 site

While your site is now launched and it’s tempting to sit back and relax, maintaining your Drupal website is important for its success, longevity and security. There are many tasks to keep your site running smoothly, from regular updates and security patches to content management and performance monitoring.

Salsa’s website support and maintenance services help you maintain and optimise your Drupal site so you can focus on your business while we take care of the technical details.

Salsa Digital’s take

Upgrading your website from Drupal 7 to Drupal 10 is crucial for the continued success of your online presence. With official support and security updates for Drupal 7 ending on 1 November 2023, it's important to start planning for the transition now.

We understand that upgrading from Drupal 7 to Drupal 10 can be a complex process, so we offer a range of End-of-Life services and options to help businesses transition smoothly, securely and affordably.

Find out more about our End-of-Life services or schedule a consultation with one of our experts.