View source for Modifying existing node servers

== Making changes to existing node servers ==
There are currently two types of node servers.  Node servers that run on a local device like a Polisy or RPi and node servers that run on Polyglot Cloud. The information below is primarily for node servers that run on a local device.

Polyglot uses the source control system called 'git' to package and store node servers. If you're not familiar with git, find an on-line tutorial now as many git commands will be used while modifying a node server.  Currently, almost all of the node servers are stored at github.com. If you're planning to send modifications back to the author of the node server, you'll likely need a github.com account. They are free.

=== Node server installation ===
When you go to the node server store and click the install button for a node server Polyglot runs a 'git' command to make a copy of the node server code on your local device.  It will do something like:

<code>
git clone https://github.com/bpaauwe/udi-weatherbit-poly.git <ns_name>
</code>

This makes a copy of the git repository that holds the node server to the local device in a location under Polyglot's control.  On a Polisy this will be /var/polyglot/nodeservers/WeatherBit for the above command.

The two main things to note here are:

* Polyglot knows the github location where the author's version of the node server is stored.
* Polyglot looks for a file in the repository called server.json and uses the node server name from that file for the directory to use on the Polisy.

At this point, you have a local copy of the node server on your local device.  You can now start modifying and testing. 

;note
:You can also create new node servers by creating a new git repository in Polyglot's nodeserver directory and adding the proper files. Polyglot will pick this up automatically and allow you to 'add it' to an empty slot to run/test/debug.

===  Making changes ===
Since you have a local copy of the git repository that holds the code for the node server, you can now start modifying it. 'git' branches are your friend here.  I recommend that you first create a new branch 'git checkout -b <my_modifications>' and leave the master branch alone for now.

However, if you do get the point where you just want to go back to the original code after you made a lot of changes, 'git' makes that pretty easy.  To reset the master branch to be identical to the master branch that exist on github do 'git reset --hard origin/master' and all the changes you made to your local copy will be undone (and lost if you didn't save them on another branch).

To test changes, you simply make sure this node server is added to the Polyglot dashboard by adding it as normal. In most cases, restarting the node server will pick up and use your changes.  Some changes may require you to 'delete' the node server and re-add it. 

=== Debugging ===
Polyglot creates a 'logs' directory and debug.log file in directory where the node server code is stored.  This file is what is displayed when you select the 'log' button on the Polyglot dashboard.  You can view this from the command line.  One trick is to start watching it with 'tail -f logs/debug.log' before you re-start the node server.  You'll get the log scrolling on the screen in real-time as you start the node server.  Use 'ctrl-c' to exit back to the command line.

=== You've fixed a bug or added a feature, now what? ===
The first step is to save the changes in your local copy of the git repository.  

To see what files you've changed do 'git status' git will then list all the files you've modified along with any new files that were added/created.

For all the files you've changed, do a:

'git add <filename>' 

If you specifically added a new file, add that also.  Don't add any of the 'untracked' files that were created by Polyglot like the logs directory and log files.

This stages the files so git now knows what files it needs to do. To actually make the changes in the repository you do:

'git commit'

git will then prompt you for a commit message.  The commit message is very important. It documents the changes you've made. Best practices here are to:

* Make the first line a short title describing the change.  I.E. Fixed bug in display of node 1's status value
* Leave a blank line
* Provide a detailed description/explanation of why this change is necessary.  I.E. Change the display so that the value has 2 decimal places of precision because the value can normally be less than 1.

By convention, all lines in the commit message should be less than 80 characters long.  This makes it a lot easier to read later.

==== Sending your change to the author ====
You did get a github account right?  The instructions below use <you> to represent your github account user name.

* From github, fork the authors git repository for the node server to your account.  This again creates a copy of the git repository.
* Add your copy as a remote to the copy on your local device.  I.E. from within the node server directory on your Polisy do: 'git remote add github git@github.com:<you>/<nodeserver.git>'
* Push your local changes to your copy on github:  git push github <branch> 

So assuming you created a branch called 'fixes' to make your changes and we're changing the WeatherBit node server:

<code>
git remote add github git@github.com:<you>/udi-weatherbit-poly.git
git push github fixes
</code>

Now all your changes are on githb and you can send them to the author. You do this by making a pull request.  When you select the 'fixes' branch on github, there will be an option to create a 'pull request'.  Click that button and github will walk you through sending the changes to the author.  The author gets notified of this.  The author has three choices of what to do with your request:

# accept it and merge it into their copy
# reject it with a request to make certain changes
# reject it