Here, I’m defining a new term for the learning debt you incur when you use a new tool within your project space. It’s the accumulation of time you’ll spend to fully understand the new tool, what it does and doesn’t do, to know when it breaks, to recognize the new error messages it throws and to learn how to “pop the hood” and investigate further when there is trouble.
“New-tool debt” is the total time you’ll need to spend because you’ve added a new tool to your project.
Don’t get me wrong, I like many of the tools available in the world of open source.
Polymer Starter Kit
I’ve decided to use Google’s new Polymer collection of code and I find myself both excited and yet daunted at the same time. Within moments, I have a template that’s generated lots of code for me and all within a new framework. And yet now I have new tools that are unfamiliar to me. I’ll walk you through the list.
Easy enough, the installation calls for the Node Package Manager but I’m already familiar with this program and of course, it’s installed already.
$ npm install
From my experience this tells npm to read the application folder’s package.json file and to update the node_modules folder with the dependencies required.
The installation of the kit requires that I first install Bower.
$ npm install -g bower
This command would install Bower globally on my system.
$ bower install
Presumably, this runs Bower in my application’s folder and uses the bower.json file in a way that’s similar to npm. The file seems to look like package.json.
Again, I’m familiar with git already as a great source control management software. Note that they indicated that this is an optional step which I should have paid more attention to. It means that in a later step, the hosting site won’t pull my code from some repository nor will it pay attention to the commit status of my individual files. This is more important than you might think since what is pushed to production should be what should be pushed to production. This isn’t the case for what comes next in their demonstration. Carrying on, though…
$ git init
This command would create a hidden .git folder and initialize it from what it sees in the current directory.
$ git add . && git commit -m "Add Polymer Starter Kit."
Here, I would be adding all files into the git system to manage them and then committing them for the current version of the project.
The installation also calls for Gulp to be added to my system.
$ npm install -g gulp
This command would install Gulp globally on my system.
What seems to be happening here is that the contents of gulpfile.js is read in by this command and then it does a number of things to collect files and to process them into a subfolder called dist under my application folder. The term they’re using is to build the source. That dist folder will be used again in a moment.
$ gulp serve
This command appears to be starting up a webserver on the localhost IP address and serving up the pages in my application folder. Note that this will show updates to individual source files like app/index.html without first running another gulp command to build them. In other words, it’s not serving up the pages in the dist folder but rather the files in my application folder.
Here in the demo Google is suggesting that I sign up for a Firebase account and push the code to this free hosting site. I then visited the website and created an account where they generated a new virtual host and URL for me. I then needed the command line interface for Firebase.
$ npm install -g firebase-tools
This would install the Firebase command line interface globally on my system.
$ firebase init
This command is supposed to ask some questions in order to create a firebase.json file in my application folder. Unfortunately Google’s instructions were lacking and it’s first necessary to run the following command:
$ firebase login
This command will direct you to the Firebase website to create a login token for use with the other commands. Having run this successfully, I was then able to run that firebase init again. It allowed me to identify the previously-created virtual host at Firebase and it was then necessary for me to identify my application’s dist folder as the source.
$ firebase deploy
This command will then take the contents of your dist folder and push it to your virtual host on Firebase to deploy to production. Note that this isn’t the way other hosting sites work, e.g. Heroku, which require the code to be pushed to a github repository first; the publishing event then pulls from your github repository. Personally, I prefer the Heroku version since it means that your code should be committed in git and pushed first to the origin repository before may be deployed to production. The Firebase version means that un-committed code can be built and deployed. To me this doesn’t seem very controlled. Returning to the Firebase commands…
$ firebase open
This convenience command will open a browser window to your remote virtual host at Firebase so that you can see your newly-deployed website.
And now here is where the new tool started to rear its ugly head. Google then asked me in the demonstration to modify the pages just slightly so that another menu item showed up. This worked flawlessly while testing locally using the gulp serve command plus edits to two files.
No longer within the scope of the their Getting Started information, I thought I’d then push these new changes to Firebase. This is when I began to have problems. And since some of these are new tools for me I felt out of my depth in handling those problems. In order to push the files from the dist folder it would be necessary to build them again:
And yet, gulp wasn’t happy. After those slight edits to both app/index.html and app/elements/routing.html the code in gulpfile.js was now failing. I reviewed the coded I’d entered in (by copying/pasting from their own website’s code) but I’d entered things flawlessly. The problem was that Google’s own people hadn’t run gulp to re-compile their own code and here I was now troubleshooting their own demo. Not fun.
At this point I found it easier to abandon changes on both of the edited files. Since I’d initialized git in the folder, this was then an option for me.
What I found frustrating is that gulp was identifying a problem with a file that simply didn’t exist within the project. Maybe this is normal for gulp but I now have the burden of of having to research what gulp does and how it fails in order to understand all this better. I’d like to use the new Polymer platform but this gulp failure is really just a wake-up call that I have new-tool debt that I haven’t paid off yet.
“…this gulp failure is really just a wake-up call that I have new-tool debt that I haven’t paid off yet.”
So be careful with what you bring into your project. There may be a point in the near future where things are breaking for no apparent reason and others are asking you why. The speed of your answer and your troubleshooting depends upon whether or not you’ve paid that new-tool debt with research.