Babel documentation since the 7 upgrade is very confusing

Original issue submitted by @JamesTheHacker in https://github.com/babel/babel/issues/8807

Since I started using Babel 7 a lot of issues in development are because of Babel issues. One day I installed a babel plugin and noticed a red warning and a link to a blog post about removing staging.

Yet nowhere is there a comprehensive guide on how to use babel without staging. Considering a lot of people will be jumping from babel 6 to babel 7 I feel it's kind of important. The decision to remove staging from what I read is to define the transforms and plugins explicitly.

I don't knock that decision, but how are people who relied on staging meant to make the switch?

I've been wandering about babel 7 for a few weeks now and end up falling into problems that cause painful hours of Googling because most of the results are for previous babel versions.

Today I got a warning about decoratorBeforeExport not being set. So I headed to the docs: https://babeljs.io/docs/en/next/babel-plugin-proposal-decorators

Nowhere on that page does it say decoratorBeforeExport is required.

A lot of tutorials and guides are on older versions that will not be compatible with 7 and as a seasoned developer - however stupid I may be - I struggled. And if I struggled you can bet your bottom dollar many others will.

I hope I'm wrong and there already exists information on this. But I can't find it.

Start with the Babel 7 migration concerns in the issue and the linked babel-plugin-proposal-decorators documentation page, especially the missing decoratorBeforeExport guidance. Map the requested Babel 6-to-7 migration and no-staging information across the documentation; done means newcomers can find a comprehensive, version-7-compatible guide and understand required plugin options.

Written by the indexing model from the issue text.