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 <http://git-scm.com/book/en/v2>. 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 On Mon, Dec 1, 2014 at 12:02 PM, Will Hopkins <[email protected]> wrote: > 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 > <https://groups.google.com/d/msgid/polymer-dev/00435461-93e5-4cf5-991a-1ceeeef5b149%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > 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/CAJj5OwA_90oU-%2B0kHsMv%2BqnU-Y2vdXGD8COk_hCYAvC%3DFV0WLQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
