There's no migration document as far as I know. As long as you didn't rely on mink too much, the migration isnt't hard.

On a high level you'll need to:

• update the configuration file (suites mentioned by you)
• update your contexts to implement the Context interface instead of extending the base context class
• instead of using sub-contexts, configure all of them in behat.yml (all contexts are equal now!)
• write a cookbook on migration ;)

I've done this in past and it wasn't really hard. However, my contexts were decoupled from mink and I didn't have too many dependencies between contexts.

I'm happy to help you with specific issues that might arise as you proceed with the migration.

We just did a successful migration from Behat 2 to 3, it was alright.

Besides the above, if you used chained steps (new Given("I do another step")) in your contexts those no longer work, you have to make direct calls to the steps.

We didn't have any to update any .feature files (~160 scenarios of varying complexity), we used DrupalExtension and Mink.

I think upgrade hurdle was always overrated. We could do better job at docs, though. @djdevin care to contribute a cookbook to https://github.com/behat/docs ? :)