addyosmani/workflow.md

## workflow.md

      
    Raw
  

              workflow.md
            
          
    A workflow for creating re-usable Polymer elements

This guide takes you through setting up the boilerplate for working on a re-usable Polymer element. It also covers the tooling to deploy a version of your package such that the master branch of your repository can be easily consumed by other apps or elements (e.g through Bower) and the gh-pages branch can be used for sharing the demo and documentation for your element.
Note: We assume you have git and Bower installed and use Scott Miles' Polymer boilerplate for getting started.
Getting setup


Create a new directory on your system for working on Polymer elements (e.g development).
Clone the untitled-element boilerplate inside this directory: git clone git://github.com/polymerlabs/untitled-element.git. Rename the element and it's files accordingly. For example, if your element was called test-element, your file list would look a little like this:


Run touch .bowerrc to create a new Bower configuration file inside your element directory. Edit the file so that Bower installs your dependencies a level up from your element. Pasting in the below should do the trick:

{
  "directory": "../"
}


Run bower install inside your element directory to install dependencies. They will end up inside the development directory if all goes well. You can now locally develop and serve your element up for testing purposes.


Deployment


Work on your element. Once you're happy with it, push your code to master in a new GitHub repo and tag a new version of it on GitHub
Grab the gp.sh script which we will use to push a demo-friendly version of your page including all its dependencies to GitHub pages
Create a new directory on your system and run gp org repo where org is the organization or username you use on GitHub and repo is the repository for your element. In my case this is gp addyosmani test-element. This will create a new gh-pages branch (or clone and clear the current one) then push a shareable version of your element.

Sharing

You should now be able to share your element. The top-level index will serve up a summary documentation page that looks a little like this:

Comments (for attributes, methods and events) will also get parsed and neatly displayed for easier reading.
It should include a demo link allowing a user to try out your element with ease.