This guide will help Stack Managers to collaborate with vendors and their development teams to create a project plan. It expands on the High Level Overview on Upgrades, and the Upgrade Guidance for Decision Makers. 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
Your development team or vendor will need to be aware of what has changed in CWP 2.x, and how that affects your codebase. Particularly if this is their first upgrade, it’s important to read through our “Technical Guidance for Developers” during the estimation phase, which includes references to changelogs and technical migrations.
The roles required for an upgrade project aren’t different from any other CWP or website project. If you have a large custom codebase, it might be worth starting with an exploratory upgrade to de-risk the process. In the early stages, it can also be advisable to keep the number of developers low. Until they’re getting the project to “dev/build” on CWP 2.x, it’s quite likely that multiple developers will end up fixing the same bugs and getting into each other’s way. Once they’re over this initial hurdle, the upgrade work can be more easily distributed to multiple team members.
We recommend provisioning at least a separate CWP environment for upgrades, keeping your current UAT environment on CWP 1.x. This retains your ability to quickly deploy hotfixes on your existing site, without switching branches or restoring database and asset states. In many cases, it is advisable to build up a parallel CWP stack with a separate production environment which you can safely switch over to during go-live. 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.
Since upgrades involve file migrations, you should ensure that you have sufficient storage space for database and asset snapshots. You can find out how much snapshot space is available in your dashboard, and can determine how much space is required by creating a snapshot. In order to restore snapshots, you also need to ensure that enough disk space is available on the target environment to extract it, in addition to the existing assets. We recommend contacting the CWP Service Desk when planning the upgrade, and discussing adding temporary environments or disk space capacity to your stack.
You’ll need to know which modules your website uses, which are supported, which are custom, and which require work to be compatible with CWP 2.x (SilverStripe 4.x).
The majority of modules in the supported modules list(external link) have SilverStripe 4.x compatibility. This can usually be determined through the module README. Your developers will be able to track down the current module by searching on addons.silverstripe.org(external link). Alternatively, you can run the first step of the upgrader tool(external link) and get a list of potential problems automatically. If the module doesn’t appear to be upgraded yet, make sure to check any open issues or pull requests (see “Maintaining your Code” and “Using Module Forks” on cwp.govt.nz). You can also search for known issues(external link), report module bugs(external link), or contact the CWP Service Desk if you’re not sure.
If you have custom code that could be useful to other agencies, this is a good time to talk to your developers about potentially open sourcing it as a module (see “Code Sharing” on cwp.govt.nz).
There is a small number of modules which are only supported in CWP 1.x (SilverStripe 3.x), and not in CWP 2.x (SilverStripe 4.x). In some cases, that’s because the related functionality has been folded into other parts of the CWP recipe. Please review the “SilverStripe 3.x only support” section of the supported modules list(external link) and check with your developers if this has an impact on your project.
CWP 2.x introduces content blocks as a way to provide more flexibility for authors in creating and structuring content. There’s also a greater potential for reusing existing code from the SilverStripe community, and a potential to reduce the custom code you maintain. Content blocks are a great opportunity to establish a pattern library on your site for a consistent user experience and less design variations to maintain. This gets you closer to a redevelopment of your site, but the payoffs for both authors and developers can be worth it. Read more about Content Blocks in the CWP 2.0 release announcement, and in our recent blog post “Let’s talk: Elemental”(external link).
Versioning of content has been implemented throughout CWP 2.x, most notably changing how the “Files” section works. If you’re currently making heavy use of file versioning, or file version history is critical to the website, then you will need to factor in some extra time for planning how you do the migration of files. Otherwise, there is a built-in file migration task which can transform from CWP 1.x to CWP 2.x compatibility (but please note that this will make existing version history of your files inaccessible through the CMS UI).
With any migration of files, you should also assess how much disk space is currently being used. A low volume of assets can be migrated locally then pushed through UAT and finally back to production during go-live, but for larger volumes there are a few things to consider:
The CWP snapshots feature is instrumental to migrate data and assets between environments. If you have access to a new parallel product environment on a separate stack, you can also move snapshots between stacks without downloading them. Long-running migration tasks are supported in CWP via the queuedjobs module(external link) which is built into the CWP recipe. See “Hosting and environments(external link)” for more infrastructure considerations.
If you download snapshots for a local migration, they need to be uploaded into CWP again. Snapshots over 256MB require Service Desk support. This may take a few days and would potentially require you to provide a physical copy of the files (i.e. USB).
If your stack has enabled the Disaster Recovery (DR) option, it may take some time for your assets to sync between data centre locations and you should factor this in to any go-live plan.
If your stack is using a large amount of disk space or has a complicated migration process, you may want to consider creating a parallel Stack running alongside your current Stack, with separate environments (including a new production environment). You can then do the migration in the background and switch over when you’re ready, with assistance from the CWP Service Desk. Some guidelines are available in our File Migration Guide(external link).
As CWP 2.x (and SilverStripe 4.x) is a major release with backwards incompatible changes, you will need to upgrade your own code to be compliant. The changes you need to make will depend on the size of the codebase, the non-standard features of the website, and custom integrations that your website may have. Your development team should be able to make an informed estimate based on the specifics of the website’s needs. Tip: You can get an overview of the size of your PHP codebase through phploc(external link).
Regression testing is arguably the most important part of any upgrade. While developers are able to do some testing as they wade through lines of code, a professional tester is able to take a step back and work closely with stakeholders to formulate a test plan. You should consider seeking the services of professional testers.
If you have already invested in automated tests for your website then you’re about to reap the rewards as they act as a safety net, catching regressions during the upgrade that would have otherwise been missed.
If you haven’t yet invested in automated tests, then now is a good time as this will provide an automated way to test critical features before you upgrade. Testing before the upgrade means you have something that tells you with reasonable certainty that your website does what you expect it to. Running them after the upgrade will alert you if something has been broken meaning you can catch bugs before pushing to production.
When deciding what features should be covered with automatic tests, you should prioritise the most critical features first and any automated tests that you’re relying on should pass before the upgrade as well as after. Check out our “Unit Testing” guide(external link), as well as NightwatchJS(external link) and silverstripe/testsession(external link) as a common combination for end-to-end testing.
A cost-effective way to spot visual regressions caused by the upgrade is to run a visual regression testing tool like wraith(external link) or Ghost Inspector(external link). They can crawl your site before the upgrade, taking screenshots of what each page looks like and then again after the upgrade. Finally, it will compare the screenshots and highlight any pages with differences.
While the CMS will have a very similar look and feel, some aspects of it may change after the upgrade. At the very least, you should plan to give content authors time to familiarise themselves with the CMS.
Training is available to agencies and suppliers to quickly get people building and maintaining websites on the Common Web Platform (CWP). Training is delivered by SilverStripe Ltd (dates and costs(external link)).
This training includes Content Management System (CMS) training for editors and administrators using the New Zealand Government Common Web Platform. If you seek training for a website that has been modified from the standard CWP install, or seek training for a SilverStripe CMS website not running on the Platform, please get in touch with SilverStripe to discuss options. Content editor training is a 3 hour course, designed to give non-technical communications and business staff the general skills to effectively use the SilverStripe CMS for publishing agency websites. Courses focus on either content editing or administration tasks based on learning requirements.
Understanding and following the SilverStripe 4 upgrade guide(external link) is the most important thing to be aware of when beginning development. Using the upgrade guide and upgrade automation tool will make your job a lot easier as it takes care of some of the code upgrade for you automatically. See our “Technical Guidance” specific to CWP.
Any modules which aren’t CWP 2.x (SilverStripe 4.x) compatible will need to be upgraded (see our guide(external link)). It’s best to do that at the start of the upgrade, in isolation from the project if possible. This allows you to test the module in isolation and ensure any problems can be found quickly and easily. Depending on how deeply integrated the module is, you could also choose to leave out the module initially and make some headway with the step-by-step guide below.
Depending on when you started your CWP 1.x site, it might have been built on the PHP 5.6 language, which is now end-of-life. You should upgrade your site to PHP 7.x, which is usually a small task. And it has an upside: both your CMS and site will likely respond faster. See our PHP 7.1 upgrade guidance on cwp.govt.nz.
After you’ve reviewed the upgrade guide and you have all modules upgraded, you’re ready to start stepping through the upgrade guide(external link). If your website relies on the CWP basic recipe, use the dedicated ‘--cwp-constraint’ parameter for the recompose command otherwise the recompose will try to upgrade your composer file to the latest SilverStripe 4.x compatible versions of modules.
As part of the upgrade, you’ll need to consider how you get your data from CWP 1.x to 2.x. The framework includes a file migration task which will help you migrate to the new file system format.
Depending on which modules you use, there may be other similar tasks providing pathways for an easy upgrade. However, you should check each module and inspect the migration task to decide whether this will work for your project since there may be project customisations which the task won’t expect.
CWP bundles the Solr fulltext search module. If your site uses this to search website content, an additional step might be needed. The module relies heavily on class names which can change with the upgrade if you’re opting to namespace(external link) your custom code. Set aside time during the migration for Solr to reindex and ensure the site can function without Solr if necessary for a short period of time.
You should ensure that you have a clear plan for go-live, including a plan to roll back should something go wrong. Provisioning a separate CWP environment for upgrades retains your ability to quickly deploy hotfixes on your existing site, without switching branches or restoring database and asset states. We recommend minimising the non-essential development work on the existing site while the upgrade is in progress. Read through the “Managing Deployments” guide on cwp.govt.nz.
Running through the go-live on UAT or another parallel CWP stack will highlight risk areas and where support may be needed from CWP Service Desk. If you find that you need this support, you should raise a ticket with the CWP Service Desk who can advise you and your team.
Before going live, you should test the features which are custom to your website. Some examples:
Search returns expected results
Login works and you can use the CMS as expected
All published files and images appear on the site
Because SilverStripe sites can be customised quite heavily, you should work with your content authors, testers, and vendors to compile a testing plan which makes sense for your context.
If you have chosen to build your upgraded site on a parallel CWP Stack, the go-live can be as simple as switching a DNS entry (see “DNS/Go-Live” on cwp.govt.nz). If you are upgrading a site in-place (on the existing Production environment), work with your vendor or in-house development team to schedule downtime during the upgrade. Every CWP site has a built-in maintenance screen, which you can use to redirect visitors during an upgrade. There are ways to bypass this screen for certain IP address ranges, which can be useful to test the new site under production before activating it for all visitors. Please talk to your developers about setting this up in an .htaccess file.