Development/Code tour

This is a quick tour of the code for new developers. All of this relates to the  directory you checked out of Git. It's presented in order of approximately how likely you are to need to know this stuff when you first start working on our project. (That is, the stuff you need most is near the start, and the most obscure stuff is at the end of the page, so if you start reading at the top you'll get the good stuff first.)

app/
Most of the code for the website lives under /app. The most important stuff is arranged according to the MVC (Model, View, Controller) layout.

app/views/
These are the web pages as viewed by a person visiting the site. If you need to tweak the HTML or display of anything, this is where it will happen. Our views use HAML, a shorthand form of markup, to generate the HTML.

app/models/
The database models. This is the area that connects to the database and converts database tables into object models that you can use in your code.

app/models/ability.rb
Code that determines what each class of user (not logged-in, logged-in, crop wrangler, admin...) can do.

app/controllers/
This area controls the app. When an HTTP request comes in from the web server, it gets passed to the relevant controller to handle. The controller generally then uses the model to fetch or modify data in the database, and presents the results via a view.

app/helpers/
Modules containing "helper" functions. The methods in app/helpers/foo_helper.rb are available from all the views in app/views/foo/, and the methods in app/helpers/application_controller.rb are available from all views (and in Growstuff, from all controllers, since we mix it into the ApplicationController class from which all other controllers inherit). We also use app/helpers for code that we wish to share between controllers - see app/helpers/notifications_helper.rb for an example. Arguably we should use lib/ for this instead.

This page has more details on how helpers work under the hood, also shedding light on how variables are shared between controllers and views. tl;dr: it is crazier than you could possibly imagine.

spec/
All the tests live in spec/, in subdirectories that look pretty much like the app/ directory.

We use RSpec to write our tests. Run them using  if you want to just run a single file or a handful of them, or with   to run the whole suite.

spec/factories
Sample data used for tests, in the form of FactoryGirl factories.

db/migrations
This directory contains scripts to alter the structure of the database. See Databases.

db/seeds.rb
This script populates the database with some initial data, including crops and test users. Run it using rake db:seed. See also Databases.

db/seeds
This directory contains support files for db/seeds.rb, such as a file containing the initial set of crops.

db/schema.rb
An autogenerated Ruby description of the database structure, used to set up the test database. Don't edit this file manually - instead, use migrations.

config/routes.rb
This file contains code to map URLs (like /plantings/new</tt>) to methods on controller objects (like Planting#new). Currently we're just using standard routing - the line resources :plantings</tt> sets up the previously-mentioned route, and also routes for /plantings/edit</tt>, plantings/$planting-slug</tt> and so on.

lib/
This directory is for Growstuff-specific classes that don't fit into the model-view-controller hierarchy. We're not currently using it much; we're mostly putting shared code in app/helpers</tt>.

lib/haml/filters
Custom filters for embedded text in HAML.

lib/tasks
Rake tasks.

lib/tasks/growstuff.rake
One-off tasks needed at various times and kept for posterity: the kind of thing we'd like to do as a migration but shouldn't, because of reasons.

vendor/
Third-party code that we can't import via the Bundler/gem mechanism (usually because we need to patch the official version in some way).