Upgrade Instructions 4.1 → 4.2

By using composer, you can update an existing installation to a specific version, without having to create a new project.

For further information on what changed please take a look at the changelog.

Instructions

As always, before doing substantial changes, make sure you create a backup of the database and files!

cd /installation-root/
# Update the core package dependencies
composer require --no-update "neos/neos:~4.2.0"
composer require --no-update "neos/nodetypes:~4.2.0"

# Update optional package dependencies (if installed)
composer require --no-update "neos/demo:~4.2.0"
composer require --no-update "neos/site-kickstarter:~4.2.0"

If you have development packages in your composer manifest, update them to match as well:

# Update development packages (if installed)
composer require --no-update --dev "neos/buildessentials:5.2.x-dev"

To upgrade an existing project to the new React UI you have to add the following dependencies. If you didn't upgrade already with Neos 4.1, you should definitely do it now.

# Change into your Neos directory
cd /installation-root/

# Flush the caches 
./flow flow:cache:flush --force

# Update the core package dependencies
composer require --no-update "neos/neos-ui:^1.4"

Attention: If your project uses custom inspector-editors you will have to rewrite them for the new UI. We prepared the package neos-ui-extensibility-examples to help you doing so.

This release includes two potentially breaking changes:

1. User Sessions now persist by default even if the normal caches are flushed. If you prefer them to be flushed you can add the command ./flow session:destroyall to your CI or execute it manually (see #1390)
2. NodeType::isOfType() now correctly returns false if a super type is removed explicitly. This is in sync with the instanceof FlowQuery filter. The change only affects the PHP API (see #1390)

# Update the packages
composer update

# Flush the caches
./flow flow:cache:flush --force
./flow flow:session:destroyAll

# Run code migrations (as needed for any packages that need to be migrated)
./flow flow:core:migrate <Vendor.PackageName>

# If not already on 4.0 or 4.1, set database charset and update to the new default given character set and collation
./flow database:setcharset

# Run database migrations
./flow doctrine:migrate

# Publish resources
./flow resource:publish 

Troubleshooting

If you run into trouble with Neos content or resources, the following may help: 

# If you get error messages when running Flow CLI commands:
rm -rf Data/Temporary

# If you experience issues with pages not working, try 
./flow node:repair

# If you experience issues with resources, thumbnail or assets, try
./flow resource:clean
./flow media:clearthumbnails