This guidance expands on the Overview on CWP 2.x upgrades, Upgrading Guidance for Decision Makers, and the Upgrade Project Plan for Stack Managers and Tech Leads. It more detail on the technical steps and considerations required to perform an upgrade of your site to CWP 2.x. It is aimed as a starting point for developers.
Alternatively, you can download the full guidance at CWP-2.x-Upgrading-Guide.pdf
CWP 2.x is built on top of Silverstripe CMS 4.x, but has additional functionality and modules. This means you need to read up about changes for both CWP and Silverstripe CMS releases. Start off by reading about the high level technical changes in the Silverstripe CMS 4 upgrading guide(external link). The main breaking changes are described in the CWP 2.0.0 changelog and Silverstripe CMS 4.0.0 changelog(external link). Since then, we have been busy releasing new minor versions of both CWP and SilverStripe 4.x. Some of these releases add new functionality. For example, Silverstripe CMS 4.1.0(external link) added support for a public/ folder, and CWP 2.1.0 added an installed modules report. You should always upgrade to the latest release, but those introduce non-breaking and opt-in changes only (our modules follow semantic versioning(external link)). You can see a full list of SilverStripe 4.x changelogs and CWP 2.x changelogs, and subscribe to the CWP Newsletter to stay in touch when new releases come out.
A lot of the upgrade effort comes down to syntax and naming changes, which we’ve mostly automated through an upgrader tool(external link). It will assist you to:
'recompose' your requirements
update your environment settings
namespace your code
update your code to use new APIs
become aware of issues by alerting you to any issues it may identify
relocate your web root assets
re-organise your project layout (more relevant with upcoming releases)
There are a lot of decision points around upgrades which are less clear than renaming PHP classes. We’ve summarised these in the “Project Plan for Stack Managers and Tech Leads”. Here’s a quick summary about the topics you should discuss with your stakeholders leading up the the technical upgrade process:
Are there module upgrade paths for all modules we’re using?
Are there modules on addons.silverstripe.org(external link) which can replace custom code?
Can we identify unused functionality and remove it?
PHP 5.x is end-of-life. Do we need to upgrade to PHP 7.x?
Should we allow more flexible content templates by rewriting our templates to use content blocks(external link)?
Should we start versioning(external link) more of our content, in order to give authors greater control over drafts and previewing?
Should we declare ownership(external link) between versioned relationships, in order to “cascade” publication events?
Uploaded files aren’t published by default. Do we need to create ownership(external link) on objects with file relationships?
Should we refactor any custom many-many relationships to a more flexible many-many-through(external link) format?
Can we use the more granular recipes to trim down or expand the modules we include in the project?
Can we increase our quality and stability by adding automation tests (e.g. via NightwatchJS(external link) and silverstripe/testsession(external link)) or visual regression tests (e.g. via wraith(external link) or Ghost Inspector(external link))