Readme is broken / v1 roadmap?

[lostfictions]

Hey there, just wanted to flag that the merge of the v1 branch into master has left the README with broken instructions. For example, these lines are based on the pre-v1 multi-class css function, whereas these lines show the new v1 single-class css usage.

I think this is a pretty urgent issue -- the upcoming documentation site isn't announced or disclosed anywhere in the repo, so the README is the first port of call to anyone coming to Astroturf or returning to it to check the docs. Currently there's no mention of the upcoming v1, no link to the new docs, no description of installation instructions (eg. "run npm install [email protected]" since by default npm and yarn won't install a prerelease), etc.

Happy to spend a bit trying to help with this, since colleagues have cited it as one thing that's made Astroturf a non-starter for them for adoption. I think it's really a shame since Astroturf is (in my opinion) one of the best, least compromised, and easiest-to-adopt css-in-js solutions out there, but doesn't have lot of uptake compared to eg. Linaria seemingly solely on the basis of its documentation.

Some potential ways forward:

• Add a mention at the top of the README that v1 is forthcoming and documentation is WIP, link to a relevant issue, and fix the most egregious errors (regardless of whether it's for consistency with v1 or pre-v1)
• Simply remove most of the README and point readers towards the v1 documentation website instead. Legacy users can refer to the migration guide on the new website -- which might leave them in the lurch a bit, but at least there's a codemod.
• Point towards the v1 website as the source of truth for v1, but also restore the README to pre-v1 state as legacy documentation for those who aren't ready to migrate. It could be renamed to a different markdown file in the repo to de-emphasize it, or it could remain as the primary readme during this transitional period until v1 launches.

---

Somewhat relatedly, I think it might increase folks' confidence in the project a bit if there were a roadmap for v1 available somewhere -- maybe that could be a pinned issue? Some people might even be able to help move things forward a bit, especially if the main tasks remaining relate to documentation and migration.

[jquense]

All good points. This encouraged me to pull the trigger on finishing up a lot of the v1 work. I've promoted the current beta to latest on npm, updated the readme and published the docs site and linked it in the repo. Next release should be a proper v1