School of hard knocks advice on packaging and distributing elements

[Will Hopkins]

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 

[Rob Dodson]

Thanks for writing this up Will. A few things to point out:

 

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.

If you do this, then run `git pull` from your local repo. That will get everything back in sync.

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.

I would also suggest the (free) Git Book. It's actually very short and gets right to the point. It has most everything you need to become proficient with git in just a few chapters

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.

I'm not sure I follow what you mean here. You can declare attributes using the polymer-element attributes="" approach and still document them using JSDoc

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.

You should edit this file with information about your own project. Otherwise, yes, bower will get confused. Make sure that when you create your tag, that this file has all the relevant info for your project and is committed and pushed to github.

I think the bower registry may reread this periodically but I took the step of tagging a new release

It does not reread. It always uses whatever the latest tag is. If you have the wrong bower.json in your latest tag, you will need to update the bower.json with the correct info and create a new tag 

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 polymer-dev...@googlegroups.com.
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.