Updating Neos – Why, When and How – 2024 edition

On this year's Neos Conference I presented a talk on updating Neos (again). I tried to answer three four questions:

1. Why you should be updating?
2. When you should be updating?
3. How to do updates?
4. What about updating to Neos 9?

The video

The conference was again streamed and recorded, so you can watch my talk below:

The slides

These are the slides for the talk:

Summary

The very short version of the talk is:

• Why?
  Because you get new features and bugfixes.
• When?
  Whenever a new version is released.
• How?
  Read & follow instructions, test & deploy.
• What about Neos 9?
  Tricky question, it depends. But generally yes. 😎

Further reading

As promised, here are pointers to more background information. I tried to group them by topic.

Going to Neos 9

This is still a fluid topic, so come back for more in the future…

• https://docs.neos.io/api/upgrade-instructions/9
• https://docs.neos.io/guide/content-repository/configuration
• https://docs.neos.io/guide/advanced/site-configuration
• https://docs.neos.io/guide/advanced/routing

Documentation

• Neos release cycle and background information: https://www.neos.io/features/release-process.html
• Release notes can be found on: https://neos.readthedocs.io/en/stable/Appendixes/ReleaseNotes/index.html
• Update instructions are linked in release announcements and collected at: https://docs.neos.io/cms/references/upgrade-instructions
• Changelogs for each branch of are in the corresponding online documentation: https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartV/ChangeLogs/index.html or https://neos.readthedocs.io/en/stable/Appendixes/ChangeLogs/index.html – use the version switcher on the bottom left!

Keeping up-to-date

• Neos announcements: https://discuss.neos.io/c/announcements/28
• Neos blog: https://www.neos.io/blog.html
• PHP versions: https://www.php.net/supported-versions.php
• Product end of life dates:
  • https://www.elastic.co/support/eol
  • https://endoflife.date/

Security

• https://github.com/FriendsOfPHP/security-advisories/tree/master/neos
• https://packagist.org/packages/roave/security-advisories

Tools

• https://packagist.org/
• https://semver.madewithlove.com/
• Composer commands:
  • https://getcomposer.org/doc/03-cli.md#outdated
  • https://getcomposer.org/doc/03-cli.md#depends-why
  • https://getcomposer.org/doc/03-cli.md#prohibits-why-not
• https://getrector.com/
• https://phpstan.org/

Code adjustment examples

Luckily most of the changes that need to be done manually are very similar across projects. So the following changes done to the sites of the Neos project can serve as examples!

The update from Neos 4.3 to 5.3 for www.neos.io took a while… Most of that was due to a lot of changes around the marketplace package. Check out the PR at https://github.com/neos/Neos.NeosIo/pull/373 and the following one at https://github.com/neos/Neos.NeosIo/pull/470 for the update to Neos 8.1.

The docs.neos.io site has seen an update from Neos 5.3 to 7.1 (https://github.com/neos/Neos.DocsNeosIo/pull/59) and smaller upgrades for the following minor versions:

• to 7.2: https://github.com/neos/Neos.DocsNeosIo/pull/63
• to 7.3: https://github.com/neos/Neos.DocsNeosIo/pull/66
• to 8.2: https://github.com/neos/Neos.DocsNeosIo/pull/100

Updates to Neos 9 will become available for your reading pleasure soonish, I hope. I'll add them here, once they get created.

For now I'll link this issue, as it shows the amount of packages (some) will need to wait for: https://github.com/neos/Neos.DocsNeosIo/issues/124

Updating Neos – Why, When and How © 2024 by Karsten Dambekalns is licensed under CC BY-NC-SA 4.0

Cover based on a photo by Clint Patterson on Unsplash