Creating a New Project & Keeping It Updated (Forking & Merging)

BelugaPod is intended to be a skeleton Ruby on Rails application that you can use as a starting point to create custom applications that interface the Beluga tracking and control code.

The basic idea is that you should fork this repository and then work from your forked repository. This page gives basic instructions on how to

1. Start using BelugaPod (i.e., fork this repository, clone it, and run the necessary set up commands)
2. Keep your forked repository updated

Assumptions

1. That you are using the command line git client (i.e., from Terminal or GitBash). If you use a GUI git client, it should provide decent help on how to translate these commands to GUI actions.

2. That you've already installed Ruby and Ruby on Rails. There are lots and lots of web sites that describe this process. Just google 'install ruby on rails mac os x' or 'install ruby on rails windows' (or whatever platform is appropriate for you).

Getting Started

1. Sign up for a free github account and log in. Make sure you follow their instructions on how to set up git and your ssh keys. Github provides excellent help pages.

2. Fork BelugaPod. The github fork help page has instructions on how to fork a repository. All you really need to do is click the "fork" button at the top of the page. This will create a repository at github.com/yourusername/BelugaPod

3. Clone your BelugaPod repository. Using the command line:

    cd ~/src  # or whatever directory you want your code to live in
    git clone git@github.com:yourusername/BelugaPod.git
   

4. Initialize the Rails app. Using the command line (note, this isn't something you can do from a git GUI):

    cd BelugaPod
    bundle install
    bundle exec rake db:migrate
   

That's pretty much it! Usage instructions will come soon. Make sure to git commit often and to use git push to push your changes to your github account.

Keeping Updated

BelugaPod is evolving. We sometimes make changes, fix bugs, or generally improve things and push to this github account. Here's how to update your own code with these "upstream" changes. The github fork help page has some additional info.

1. Add this repository as a 'remote' to your own repository with the name 'upstream':

   git remote add upstream git://github.com/leonard-lab/BelugaPod.git
   

2. Fetch the changes from the 'upstream' remote and merge them into your own code (make sure to commit your own work first):

   git fetch upstream
   git merge upstream/master
   

   If you have any conflicts, you'll need to resolve them manually. There's some help on this github page about branching. There should also be lots of info if you google 'git merge conflict'.

3. Update your gems (ruby libraries that the app needs):

   bundle update
   

4. It's possible you may need to update your database:

   bundle exec rake db:migrate
   

Note about gems

BelugaPod uses two gems that we created: rhubarb and BelugaIPC. These can get updated separately from BelugaPod. You may be using BelugaIPC to run the Matlab Beluga simulator. You can always update that code using steps 1 & 2 above if you've forked BelugaIPC or just by doing a git pull if you've cloned our repository (which is probably what you should do unless you have a good reason to need to modify that code). However, the versions that BelugaPod needs are specified directly in BelugaPod's Gemfile, and therefore will get updated automatically when you run bundle update.