Upgrading from Craft 2 to Craft 3: Should I update?
The Craft documentation is a great place to start if you are updating from Craft 2 to Craft 3. If you haven’t already, read over the Upgrading from Craft 2 and Changes in Craft 3 pages. You’ll likely refer to these pages throughout the migration process.
The series of articles below are not meant to be a replacement for the docs but to provide a compendium of notes, considerations, and workflow preferences that I’ve found to complement the guides above while upgrading several Craft sites. These articles will cover:
- Evaluation, Setup, and Planning
- Update Everything on Craft 2
- A Fresh Craft 3 Install
- Database Migration (coming soon)
- Template Migration (coming soon)
- Custom Plugins & Modules (coming soon)
- Deploy & Maintain (coming soon)
Evaluation
Before you agree to upgrade a site to Craft 3, you’ll want to review the site and confirm that it’s possible to do so. One part of this question is if it’s technically possible (which it usually is). The more liking binding consideration is if a budget will be able to cover the work involved.
The primary blockers I’ve run into for sites upgrading to Craft 3 are on sites with lots of custom development and sites using plugins that have not yet been (or will not be) upgraded to Craft 3. Both scenarios result in additional budget considerations as, while the general upgrade process is fairly straightforward and reasonable for most budgets, these scenarios lead to additional custom development considerations.
To start off, open your favorite spreadsheet tool or text editor and review all the plugins on your site. List out each one, do your research, and identify its upgrade path for Craft 3. If a plugin doesn’t have an upgrade path, you’ll need to decide whether you want to wait for the developer to update it (assuming they will) or find an alternative path (such as rebuilding it yourself, assuming they won’t be upgrading it). Both paths are reasonable depending on your project requirements.
This step can be tedious if you have lots of plugins. Craft provides an overview of what it knows about your installed plugins at the bottom of the Craft 2 update page. That information is maintained via the craft2-plugins.php file on the Craftnet repo if you want to propose an update to the information you see there. If you can’t determine your upgrade path from there, you may need to look up various plugins individually.
If you’re on an older installation of Craft, be sure to read over the Server Requirements for Craft 3 and make sure you meet the PHP and MySQL requirements. If you don’t, you may have to plan and budget for getting upgraded to a new server as well.
Subscription pricing
On the business side of things, now is also the time to begin the conversation with your employer or client about Craft 3's new subscription model. This will feel like a big change for many but the subscription model is a much better reflection of the ongoing costs of maintaining a website over time so it's well worth the time to review your pricing, educate your clients, and get folks on board.
While many Craft 2 sites will be grandfathered into licenses that won't have renewal fees, any new plugins added in the future will be subject to the new model so it's worth making sure everyone understands the changes that are happening to the ecosystem upfront.
The content migration
While it can feel premature, determine how you expect to deploy the updated Craft 3 site.
On many sites, content editors will need to continue making updates through part of the time you spend on the migration and this will lead to the current production database and the newly migrated database getting out of sync. Depending on the needs of your project, the workflow around the database updates can take several different forms:
- The Long Content Freeze
For smaller sites, informational sites, and sites without user-created content, you can often agree (along with whoever else edits the site) to not make changes to the production database while you perform the Craft 3 updates. As these types of sites have less frequent changes, you can often agree to do this for a couple of days or a week and give yourself plenty of room to perform the updates needed. Once you complete the migration you can upload the new database and replace the old one as you deploy your new files. - The Short Content Freeze
For sites that have more regular updates but where you also have access to the whole team making the changes (i.e. no user-generated content), it may be harder to ask people to stop making changes for a long period of time but as this is a major upgrade, you can likely agree to a 1-day window for the migration where no changes are made to the website. If a 1-day window during business hours doesn’t work, you may have to discuss what type of window could work outside of normal business hours. In these cases, you can perform your migration on a representative database in a local development environment to work through any issues you might run into along the way and re-run the migration on the live database during the content freeze. This process requires a bit more planning as any database changes you make during the initial migration process (take good notes!) will need to be made a second time when you run the final migration on the production database. We’ll discuss considerations on how to plan your workflow for this type of migration throughout this article. - The Conditional Content Freeze
For sites with frequent updates or user-generated content you may run into tricker scenarios where you'll be unable to coordinate directly with who is updating content. These cases will likely need to be dealt with on a case by case basis as businesses and communities can vary in their expectations. Some techniques for this scenario include making a public announcement about a maintenance window, disabling certain features on the site for a period of time so content isn’t updated when you don’t want it to be, and preparing programmatic migrations to ensure you can move quickly in the window of time you have to make updates.
New skill considerations
For the designers, junior developers, and one-click-updaters out there, there is one more area I’d encourage you to plan ahead for: your skill set.
Be honest with yourself and honest with your clients or employer. While you may really, really want to upgrade to Craft 3, don’t let the pretty UI fool you. Craft continues to be a custom CMS and requires a certain amount of development knowledge to use and maintain properly. Craft 3 introduces an entirely new architecture and relies on technologies like Composer that may test your skill set when things go wrong. Craft 3.1 and 3.2 are also fairly big updates and can introduce a variety of other factors to consider while updating.
If you are not using a repository like git to manage your codebase and deploying your updates using a deployment tool, it may be best to first take the time to learn and become comfortable with those skills.
Plan some time for a contractor or coach in the budget to help level-up and avoid common problems along the way. Straight Up Craft offers integrated coaching and training services and there are several qualified agencies and developers in the Craft community who can help you out too.
Custom development and migrations
In the case you will need to do any custom development or data migrations to get upgraded, you may want to jump ahead to step 6 and plan those out specifically. While, as far as complexity goes, I’ve placed the Custom Development section toward the end of these notes, practically speaking, that development is probably going to have to happen first so that it is ready when you are performing the upgrade process.
In the next article, we'll begin the upgrade: Update Everything on Craft 2
This article is part of a series:
- Evaluation, Setup, and Planning
- Update Everything on Craft 2
- A Fresh Craft 3 Install
- Database Migration (coming soon)
- Template Migration (coming soon)
- Custom Plugins & Modules (coming soon)
- Deploy & Maintain (coming soon)