Architecture

[jay-snee]

Let's get some discussion going on around the application architecture. I know there's a lot of JS folks in here who might not be looking to get down and dirty on the Ruby side of things, so I propose make a complete split between the backend data handling and the frontend UI clients.

Backend

I think we should create a Rails backend application that'll house the admin UI and provide JSON REST API endpoints to supply front end clients with their data. This would be sat on top of a Postgres database which would handle the long term object storage. We'd define object models within Rails as part of the initial build and rely on ActiveRecord to abstract away the SQL and keep the code clean. Database initialisation and so on is all handled by the default Rails Rake tasks so people unfamiliar with Postgres needn't worry.

We'd then build out the application, using user stories as work units, with a 'behaviour driven development' process (you define the goal of whatever you're adding as a test, and then implement the feature ensuring that when you're done your initial test passes, as do all of the previously added tests). I'd like to use Rspec and Capybara as the test frameworks, with Travis handling continuous integration.

This backend application will have two interfaces - a standard HTML interface written in Haml, Coffeescript and Sass (pretty much the defacto standards when working with Rails, given that's what people are looking to learn) used for administrative access to the data and any application wide settings plus a JSON data API for our front end/3rd party applications to use. We'll namespace the API routing (/api/v1/, /api/v2 etc).

Frontend

I'd quite like to include an Ember front end to consume the API as part of the application codebase (I know Ember's been mentioned elsewhere and I've used it - albeit not extensively - before), although I'm happy for anyone else's input here as this isn't really my area of expertise.. Given we're providing the data via JSON anyway, there's nothing to stop us having multiple UIs here.

Environment

Given the disparity between the systems people are developing on, I also propose we set up a Vagrant profile so everyone's working in the same system environment. We'll be looking to handle authentication with the Devise and Omniauth gems and using the Puma web server. Initially, I'd also suggest deploying to Heroku because free is good.

[JamieAmstel]

Nice job @jay-snee, just something to add that I would also be happy using Ember for the front-end connecting to the REST api and dealing with the JSON, from what I understand @joshfarrant already has some experience with this too.

Regarding coffeescript is this standard to be used? Most people seemed to rather use plain JS from when you asked this question in Slack.

I have been doing a little bit of research into RoR getting ready for this, also just wanted to say I really appreciate you stepping forward and leading us into a new language as a first project with the group. :+1:

[jay-snee]

@amazingdetective Have a read through this for a bit more on the Coffeescript stuff - http://guides.rubyonrails.org/asset_pipeline.html Haml usage isn't default (and replaces Erb), but it's worth using as that's what most rails shops use and it's really beneficial in imo.

Glad to hear people are up for the Ember side of things, as that's what I'll be looking to learn from this. That and working with other people for a change!

Also I forgot to mention earlier, I'd like to hook CodeClimate into the build process so we've got automated code reviews too..

Once people have had a chance to chip in here with any concerns and such I'll get the app initialised and setup with the right gem dependancies so people can start getting stuck in..

[kevinzurek]

Everything discussed here sounds good to me. I don't usually use frontend js frameworks in my projects, but i'd like to learn something other than Knockout. @jay-snee you're awesome for setting this up with rails!

What do you usually use for an IDE? I know RubyMine has a 30 day free trial and Jetbrains is really good about giving licenses for open source projects after the trial period.

Also - is everyone familiar with the git forking workflow? Let's initiate a repository, set up permissions, and make some forks!

[jay-snee]

Personally I use SublimeText though I've used Atom for a while too and that wasn't bad either. I'd stay away from IDEs and stick to your more standard text editors, especially at this stage. There's a lot of 'magic' within in Rails that can be confusing initially and if you add an IDE in to that then you're going to have a lot less of an idea as to what's going on.

[JamieAmstel]

Thanks for all the extra info, I've been testing out Brackets personally. I see you've made some commits @jay-snee so I am going to test setting up ruby on rails on my machine to do some initial testing. :-)

[jay-snee]

@amazingdetective If you give me about 30 mins I'll push the Vagrant build files up, just running it to make sure it grafts now..

[JamieAmstel]

Thanks @jay-snee, I've yet to use Vagrant but I've been meaning to put time aside for it, looks like the ideal time to get used to it right here. For now however.. success

[JamieAmstel]

I had to do a bundle update to get your commit to work but all is running fine although I'm unsure what's different from the basic rail app setup. I did a little testing around and am very impressed!

[jay-snee]

@amazingdetective bundle install or just bundle were the commands you were looking for.. In other news, Vagrant's still giving me shit - sorry for the delay with that. Not entirely sure if it's a local system issue or a problem with the Trusty Unbuntu setup. I'll push what I've got to a branch at some point so other people can take a look. Anyway, here's some preliminary info on the Gem system...

Gems & Bundler overview

Gems are self contained ruby libraries that provide additional functionality to ruby applications. Rails uses the bundler gem for dependency management. Gems are acquired from https://rubygems.org.

Within a Rails application, required gems are listed in the Gemfile. Here we can list which gems we require for our application, and which version of said gems we want to use. We can also list gems for specific application environments (development, test & production) using 'groups'.

Gems are not packaged within the application. Rather, after running your git clone you should then run bundle install to automatically download and install all application dependencies onto the host system. This will install the required gems at their versions listed in Gemfile.lock. Gemfile.lock is an auto generated file created and updated when you run various bundle commands. It should not be edited manually. It also explicitly includes any dependancies for the gems themselves.

When you run bundle update, Bundler attempts to install the latest version of all required gems that don't have specific version requirements listed in the Gemfile and updates Gemfile.lock. Potentially, this can introduce incompatibilities and discrete errors can surface and is something I generally avoid unless I have a specific need to update a gem.

Once installed via the bundle install command, gems are available to all applications using the same version of ruby. I'd recommend looking into rbenv for managing ruby versions.

Gems we're using in this project

Asset pipeline

We're using the following gems to handle asset compilation, preprocessing, minifying, importing major libraries and so. therubyracer in particular is worth reading up on.

1. gem 'sass-rails', '~> 5.0'
2. gem 'uglifier', '>= 1.3.0'
3. gem 'coffee-rails', '~> 4.1.0'
4. gem 'haml'
5. gem 'therubyracer', platforms: :ruby
6. gem 'jquery-rails'

With these gems listed in the installed we can use Rails default rails generate (aliased to rails g) tasks to create boilerplate assets in the correct formats (haml files instead of erb etc).

Testing

1. gem 'rspec'
2. gem 'rspec-rails', '~> 3.0'
3. gem 'selenium-webdriver', '~> 2.44.0'
4. gem 'capybara'

Testing is a big subject and I'd recommend doing your own research in to this, alongside the project. We're using Rspec as the primary test framework. Rspec is comprised of a number of components, initially I'd recommend reading up on Rspec-Core to get an idea of how tests should be written.

Additionally we're using Capybara with the Selenium Webdriver as our acceptance testing framework. Using these components we can describe 'features' of the application using the Capybara DSL. These tests describe how specific interface features of the application (logging in, creating a project etc) should work, and provide an automated way to verify that using selenium with either headless or full browser instances.

Since we've included and installed Rspec into the application, assets (models, scaffolds etc) generated using the rails g command should automatically create boilerplate spec files in the spec/ directory.

Other gems of note

There are a few more gems listed in the Gemfile that I'll not get into just yet, but a couple of others of note at the moment are:

1. gem "puma" - The Puma web server is a multithreaded ruby application server which replaces the default Webrick used by Rails applications. Prior to January this year, Unicorn was the generally recommend web server for Rails applications. However after a slow client attack that could by exploited against the Unicorn web server was discovered, it's now considered prudent to use Puma instead. You can read more on Puma configuration here
2. gem 'rails_12factor' - Adds support for some Heroku platform specific features, inline with the ideas discussed here (definitely worth a read).
3. gem 'jbuilder', '~> 2.0' - DSL for creating JSON data structures (Rails default gem) - https://github.com/rails/jbuilder

[jay-snee]

Vagrant provisioning is working, updated readme.

[JamieAmstel]

@jay-snee understood! Did you have a look at my pull request? I did some playing around with adding input to a database