I've been working through the process of packaging and distributing an element following the instructions at
- packaging: https://www.polymer-project.org/docs/start/reusableelements.html - distributing: https://www.polymer-project.org/articles/distributing-components-with-bower.html As a newbie to git, github and bower I found a few gotchas in the documentation and a few pieces of conceptual knowledge that were invaluable. For others that may follow I thought I try and save you some time by augmenting the documentation with this post. In the following I assume that you have successfully installed npm, git and bower and have managed to use bower to install Polymer. You should have a GitHub account. I should also point out that I am using Windows 7 as my local machine. Packaging: 1. I suggest that you use the Git Bash shell for all your work rather than Windows cmd. You should find Git Bash under the start menu All Programs>Git>Git Bash. You should get a cmd like window with a $ prompt when you run this. 2. Remember that Git Bash uses Unix like syntax for path names so replace back slashes with forward ones and enclose any names with spaces in quotes. 3. Under the Develop and Test instructions if you are using Python 3 (rather than 2) for your local web server the command you should use is python -m http.server 4. Under the Deploy instructions there is a link to create a new repository on github. When you follow the link you will see a checkbox for "Initialize this repository with a README". *DO NOT SELECT THIS OPTION*. If you do GitHub and your local git will be out of sync. If you select this by accident then delete your repository on github and start again. 5. Of course I made the above mistake. As a result I found a really good conceptual discussion of how git works here. http://www.sbf5.com/~cduan/technical/git/ -- if you are new to git* I SUGGEST YOU READ THIS*. 6. As part of these instructions you are invited to tag a release. This seems a bit out of order to me as you are then going to update your project to include a demo file etc. I suggest you defer tagging a release until you are done these steps 7. Under "Publishing a Landing Page and Demo for your element it is well worth spending the time to understand what the Polymer team has done with Index.html and JSDocs. The Index.html page will read your custom element and build documentation based on JSDoc tags in your element. Typically these are flagged with an @. To get a nice rendering of your elements attributes and keep everything in one spot you will see that attributes are best declared as part of your Polymer javascript function rather than the attributes facility of polymer-element. This somewhat contradicts advice given elsewhere to use attributes. *This is a really nice facility*. 8. Once you have your Demo page and you are satisfied with how Index.html looks locally then commit these changes via git and push the changes to github. 9. The next step (still under the same heading) is to create a temporary directory and run a script called gp.sh. The purpose of these steps is to create a new branch in your repository called gh-pages that includes all of the dependencies. I guess this is so you can do one install and get your element and Polymer all in one fell swoop. Unfortunately the script uses SSH to communicate with github so you need to have SSH set up to run this script. To set up SSH see https://help.github.com/articles/generating-ssh-keys/. You may need to start the SSH agent see http://stackoverflow.com/questions/17846529/could-not-open-a-connection-to-your-authentication-agent 10. Also there is an open issue with gp.sh and SSH see https://github.com/Polymer/tools/pull/27 Distributing: 1. I suggest you read http://bob.yexley.net/creating-and-maintaining-your-own-bower-package/ which gives a good overview of bower and points out one really important fact (which I will discuss below) 2. You may have a bower.json file in your element's directory -- perhaps from the seed element. I suggest you delete this file and start afresh. 3. After you create your bower.json file with bower init make sure this is committed to your local repository and pushed to github. The reason for this is that the bower registration server reads the bower.json file on GitHub *NOT ON YOUR LOCAL MACHINE* -- this was the key piece of understanding I missed before reading the link above. 4. If you screw this up and I did (I had the bower.json file from the seed element sitting on GitHub) simply fix the bower.json file locally, commit and push. I think the bower registry may reread this periodically but I took the step of tagging a new release. Hope this was of some assistance. Happy packaging and distributing. ps Please feel free to point out any mistakes in the above or add your own tips Follow Polymer on Google+: plus.google.com/107187849809354688692 --- You received this message because you are subscribed to the Google Groups "Polymer" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/00435461-93e5-4cf5-991a-1ceeeef5b149%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
