diff --git a/README.md b/README.md index e801eca38..ad3e085e8 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,22 @@ polymer-modulizer is a tool to convert packages of HTML imports to JavaScript modules. +## 🚧 Warning: Extremely Early Preview! 🚧 + +polymer-modulizer, and the output it generates, are very early versions. As far as we can tell, they mostly work, but they're still subject to bugs, unexpected behavior, breaking changes, and especially, too little documentation. + +We are opening this tool now so we can work in the open, and to gather feedback on how well it works on your code. If you choose to use it: + + 1. 🚿 Run the tool in a clean Git working directory, or use workspace mode. Do not run on uncommitted changes. + 2. 📞 Please report any issues you find! + 3. 👷🏽‍ Pardon the dust. Some parts of the workflow, like testing the output of multi-package conversions, are still under construction. + 4. 🔄 Be ready to update and run the tool again in the future to pick up changes in output. + 5. 📚 _If_ you want to publish the output of the tool, use a pre-release version and tag for now, until we can make stronger garuntees about the API of the output it generates. + +Good luck, the future is exciting! 😎 Please join us for discussion in the [`#modulizer` Slack channel](https://polymer.slack.com/messages/G6R11FXEC/). + +## Overview + polymer-modulizer is designed to convert HTML Imports, and especially those containing Polymer and Polymer elements, to JavaScript modules as automatically as possible. polymer-modulizer tries to strike a balance between supporting the general semantics of HTML Imports and generating idiomatic JavaScript modules. It converts assignments to global namespace objects to module exports, and references to namespaces as imported names.