In December 2016 we branched version 3 of Neos and version 4 of Flow. So far a final release has not been made, but why? One of the reasons is that we are still working on making an upgrade as easy as possible and need to iron out some remaining issues.

This post shall give you a glimpse in what it took me to update this very website to the current state of Neos 3.0…

The hardest part right now is to actually get composer to install Neos 3.0. If you are like me you do not want to simply set the minimum required stability to dev, so finding out which packages you need to whitelist in your composer root manifest is the first step, along with actually requesting Neos 3.0. For me, this looked like this:

    "require": {
        "kdambekalns/karstendambekalnsde": "dev-master",
        "robertlemke/plugin-blog": "@dev",
        "m12/flow-rollbar": "dev-master",

        "neos/content-repository": "@dev",
        "neos/fusion": "@dev",
        "neos/imagine": "@dev",
        "neos/media": "@dev",
        "neos/media-browser": "@dev",
        "neos/neos": "@dev",
        "neos/nodetypes": "@dev",
        "neos/party": "@dev",
        "neos/setup": "@dev",
        "neos/twitter-bootstrap": "@dev",

        "neos/cache": "@dev",
        "neos/diff": "@dev",
        "neos/eel": "@dev",
        "neos/error-messages": "@dev",
        "neos/fluid-adaptor": "@dev",
        "neos/flow": "@dev",
        "neos/utility-arrays": "@dev",
        "neos/utility-files": "@dev",
        "neos/utility-lock": "@dev",
        "neos/utility-mediatypes": "@dev",
        "neos/utility-objecthandling": "@dev",
        "neos/utility-opcodecache": "@dev",
        "neos/utility-pdo": "@dev",
        "neos/utility-schema": "@dev",
        "neos/utility-unicode": "@dev",

        "neos/form": "@dev",
        "neos/googleanalytics": "@dev",
        "neos/seo": "@dev",
        "neos/swiftmailer": "@dev",

        "jonnitto/smartlook": "@dev",
        "moc/imageoptimizer": "@dev",
        "robertlemke/akismet": "@dev",
        "robertlemke/rss": "dev-flow4-compat as 1.1.1"
        "ttree/oembed": "dev-flow4-compat as 3.0.0",
    },
    "require-dev": {
        "neos/buildessentials": "~4.0@dev",
        "mikey179/vfsstream": "~1.6",
        "phpunit/phpunit": "~5.4",
        "neos/behat": "dev-master"
    },

This is complemented by a list of fork repositories on GitHub and some small adjustments to the scripts section of the manifest. The gist of what needs to be done is in this gist, which will be made available for everyone to use (Update: now even as a phar archive from this project):

As soon as composer updated all packages to the expected versions (which needed some PRs to Neos-maintained packages) I could actually make the packages that needed it compatible to Neos 3.0 and Flow 4.0 respectively.

This was mostly a question of running core:migrate on them one by one, checking the results and adding some finishing touches. There were only very few minor issues where the migrations did something that I really had to fix manually, otherwise they worked fine. Those were:

• Some leftover \Neos\Fusion\TypoScriptObjects\AbstractTypoScriptObject. Even though the AbstractTypoScriptObject still exists (marked deprecated), the TypoScriptObjects is gone and must be FusionObjects. Update: see this PR.
• Injecting settings using Flow\Inject(setting=…) no longer works and leads to a (rather cryptic) error. It needs to be Flow\InjectConfiguration(path=…) now.
• An issue with YAML migrations
  

What do we learn?

This took me the better part of three days, but don't let that fool you:

1. A number of issues I ran into are fixed in Neos and Flow now.
2. All packages I made compatible with the new versions are ready for you now.
3. More issues will be fixed by the time the release is stable… :)

How easy an upgrade will be for you, depends largely on the number of third-party packages you use: A plain Neos site with none or little dependencies is easy to update, it get's more complex with a larger number of dependencies.

Exhibit A

PRs created along the way:

• https://github.com/neos/neos-googleanalytics/pull/14 (merged)
• https://github.com/neos/neos-googleanalytics/pull/15 (merged)
• https://github.com/neos/neos-development-collection/pull/1383 (merged)
• https://github.com/neos/flow-development-collection/pull/826 (merged)
• https://github.com/neos/flow-development-distribution/pull/17 (merged)
• https://github.com/neos/neos-googleanalytics/pull/16 (merged)
• https://github.com/million12/Flow.Plugin.Rollbar/pull/1 (merged)
• https://github.com/robertlemke/RobertLemke.Rss/pull/5 (merged)
• https://github.com/robertlemke/RobertLemke.Akismet/pull/6 (merged)
• https://github.com/robertlemke/RobertLemke.Plugin.Blog/pull/19 (merged)
• https://github.com/mocdk/MOC.ImageOptimizer/pull/16 (merged)
• https://github.com/jonnitto/Jonnitto.Smartlook/pull/1
• https://github.com/dfeyer/Ttree.Oembed/pull/7