Here’s a quick start checklist to get the ball rolling. It builds on the High Level Overview for CWP 2.x Upgrades. There’s a more in-depth guide to create a Project Plan for Stack Managers and Tech Leads. If you are a developer, you'll also want to read the Technical Guidance for Developers.

Alternatively, you can download the full guidance at  CWP-2.x-Upgrading-Guide.pdf

Discover the benefits

Consider the specific benefits of upgrading depending on the version that your site is currently on.You can find out what version you are on by asking your developers to use the CWP site summariser(external link) or checking your environments on the deployment dashboard.

Dashboard screenshot

Then ask your developers to look at the changelogs for the newer versions to see what features you’re missing out on!

For example, if you find you are on CWP 1.9 / Silverstripe CMS 3.7, look at the changelog for the next stable release (e.g. CWP recipe basic 2.0.0). And if you are on CWP 1.6 / Silverstripe CMS 3.6, look at the changelogs for the 1.7, 1.8, 1.9, 2.0, 2.1, 2.2... stable releases. The further behind you are, the more you can gain by upgrading.

To see a full list of CWP changelogs and the corresponding Silverstripe Framework version, see the CWP releases and changelogs page.

Evaluate the risks

What modules does your site depend on? Are they up to date? If you are using non-recipe modules, ensure the site has been penetration tested. Use the Site Summariser if you are on CWP 1.9 or above. Alternatively, talk to your developers or log a Service Desk ticket. Try to familiarise yourself (at a high level) with the process of upgrading a CWP/Silverstripe CMS site. In order to deliver the benefits of CWP, upgrading your CWP site is not like upgrading a simple SaaS product. Make sure you have a technical leader to assist you and make sure they read the sections relevant to them.

Assess your use case

If you are on CWP 1.9, use Site Summariser to assess which modules you have. As covered in the FAQs, the modules you are using affect the complexity of your upgrade. At the low complexity end of the scale are sites using the Wātea theme modules. At the high end of the scale are sites using modules that haven’t been open sourced.

Assess your quality assurance practices

Do you have existing automation tests (unit, integration, end-to-end)? Are they currently passing, and do they provide sufficient cover for the features important to your agency? This might be a good opportunity to talk to your developers about future proofing your site by building up testing practices (see our guide(external link)).

Determine hosting options

Each CWP environment has a UAT and Production environment. During the upgrade, you’ll likely want additional environments in order to prepare and test upgrades. In some cases, upgrades involve long-running migration tasks, especially if your website has a lot of assets. There can be database and search index changes which take some time to roll back in case of errors. Depending on your risk assessment, there are a few options for provisioning environments for your upgrade.

Option A (recommended for high complexity sites)

Set up a new parallel Stack that is the same as the existing site, load up a copy of the site and all the assets, and update there. Once you know you are good with everything, transfer over refreshed assets, then switch the domain to point to the new Stack and you are done!

Pros: No downtime as you are building in parallel, less impact (i.e. data and cost) if there are issues, no expensive out of hours go-lives, and less overall risk.
Cons: Paying for two Stacks at once.

Option B (recommended for low complexity sites)

Set up a new environment on the existing stack, deploy through to the existing UAT and Prod.

Pros: Less expensive at the beginning as a new environment costs less than a Stack, much faster/easier to transfer around code and assets.
Cons: Higher risk and potential for costs to be greater than setting up a new Stack; downtime during go-live; potential out-of-hours costs if needing to be done outside of business hours.

Option C (alternative for low complexity sites)

Use existing Test or UAT environments for the upgrade.

Pros: No cost impact, no reliance on CWP Service Desk.
Cons: Higher risk for go-live (see Option B). Hard to test changes to your existing CWP 1.x website without restoring asset and database state prior to the in-flight migration on that environment.

Any temporary environments required for CWP 2.x upgrades don’t incur setup fees in the CWP Service Desk and you can cancel them once they’re no longer required. New parallel Stacks do incur a setup fee to cover the additional configuration needed to make it production-like but the monthly fee is considerably discounted.

Start a Project Plan

Work with your vendor or in-house dev team to create a project plan (see our Project Plan for Stack Managers and Tech Leads(external link)).

Get a quote and set a budget

Ask your vendor or in-house dev team for an estimate and budget accordingly. Factor in the costs for development plus hosting. Schedule an upgrade with your in-house team or vendor of choice.

Perform the upgrade

Your in-house dev team or your vendor will run a practice deployment, test it, and then go through UAT testing and bug fixes. Tests should be at a code level and at a user level. The Project Plan for Stack Managers and Tech Leads(external link) has more guidelines on what to consider during testing.

Further reading

Last modified: