Add rails glossary of common terms & concepts

2 files changed, 428 insertions, 0 deletions

diff --git a/railties/guides/source/credits.html.erb b/railties/guides/source/credits.html.erb
index da6bd6acdf..00cf765b77 100644
--- a/railties/guides/source/credits.html.erb
+++ b/railties/guides/source/credits.html.erb
@@ -70,3 +70,7 @@ Ryan Bigg works as a consultant at <a href="http://rubyx.com">RubyX</a> and has
 <%= author('Heiko Webers', 'hawe') do %>
   Heiko Webers is the founder of <a href="http://www.bauland42.de">bauland42</a>, a German web application security consulting and development company focused on Ruby on Rails. He blogs at the <a href="http://www.rorsecurity.info">Ruby on Rails Security Project</a>. After 10 years of desktop application development, Heiko has rarely looked back.
 <% end %>
+
+<%= author('Adam Hawkins', 'adman65') do %>
+  Ruby developer and founder of <a href="http://threadedlabs.com">ThreadedLabs</a> a modern web shop. You can read his blog at <a href="http://broadcastingadam.com">Broadcasting Adam</a>
+<% end %>
diff --git a/railties/guides/source/glossary.textile b/railties/guides/source/glossary.textile
new file mode 100644
index 0000000000..099a35bc52
--- /dev/null
+++ b/railties/guides/source/glossary.textile
@@ -0,0 +1,424 @@
+h2. Rails Glossary
+
+This is a beginner guide to common terms, projects, and things you will come across when
+working with Rails. The glossary is here to provide you introductory material on each 
+topic so you can learn more. When you come across a topic you're not familiar with,
+you can check here.
+
+endprologue.
+
+h3. Acceptance Testing
+
+Acceptancing testing is the act of testing use cases. Test cases are written 
+in a way that describes a use case. Then a test case is passing it can be 
+accepted. Cucumber is a good tool for acceptance testings. Work with your 
+stake holder to develop tests that represent use cases. When the test is 
+complete the feature should be accepted. Acceptance testing is focused 
+around people outside the code development accepting features.
+
+h3. Application Servers: Thin, Passenger, Unicorn
+
+These are all application servers. They interact with your Ruby code 
+and respond to requests. They are integrated with web servers like Nginx 
+or Apache to server you application on the internet. Some also serve
+the application by itself. You can +rackup+ a rack app and serve it with
+Thin right away.
+
+h3. Assets
+
+Assets are static files that are part of your application. They include: images, sytlesheets, scripts, or fonts.
+Essentially, anything that needs to be server with your code for your app to run is 
+an asset. The asset pipeline gives you an easy way to manage all the different files.
+
+h3. Authentication
+
+Authentication is the process of matching credentials to a person and 
+verifying them. Authentication is purely about identifiying who the 
+user is–and not what they can do.
+"Sorcery":https://github.com/NoamB/sorcery is an example of an authentication library.
+
+h3. Authorization
+
+Authorization is the process for determine what a specific user can do. 
+Authorization usually involves permission or role based systems. 
+"CanCan":https://github.com/ryanb/cancan is an example of an authorization library.
+
+h3. Behavior Driven Development (BDD)
+
+Is essentially the same as TDD except using a different set of tools 
+to express code in terms of user facing behavior. 
+"Rspec":https://github.com/rspec/rspec and "Cucumber":https://github.com/cucumber/cucumber are part of the BDD toolbox.
+
+h3. Bundler
+
+Bundler reads a Gemfile and calculates a set of version requirements 
+to make all the specified gems live happily together. It will prevent
+version conflicts and infamous ‘gem already activated error’. It allows 
+you to install git gems or standard gems from rubygems.org. It does 
+not require libraries, it simply makes them available. It is up to you 
+require them in your programs. However, Rails will automatically setup bundler when your application boots.
+
+h3. Capistrano
+
+Capistrano is a tool for executing command one groups of remote 
+(or local) serves over SSH. It is primary used to deploy
+Ruby (on Rails) applications. It has support for multistage environments. 
+Example, staging and production. You can easily write your own 
+tasks similar to writing rake task. It is the preferred way deploy Rails applications.
+
+h3. Capybara
+
+Capybara is a gem designed to provide an abstraction layer between 
+different browser drivers. It is primarily used in integration testing 
+to interact with the web server. It provides an API to navigate between 
+pages, click buttons, fill in forms, and other user interactions. It has 
+adapters for many different browser drivers. Notable drivers include 
+Selenium, rack-test and webrat. It is primary used in acceptance testing.
+
+h3. CoffeeScript
+
+CoffeeScript is a JavaScript superset. It aims to solves some problems
+with JavaScript. It has some syntatical sugar around creating colsures and
+objects. It supports for splat arguments. CoffeeScript files are compiled
+into JavaScript files. CoffeeScript is usually called CS. You'll often see
+CS/JS in reference to CoffeeScript and Javascript.
+
+h3. Compass
+
+Compass is a library built around SASS abstractions. It provides mixins 
+for many common things like styling buttons and forms. It is also easy 
+to extend and comes with many built in functions. The blueprint CSS 
+framework is bundled by default.
+
+h3. Cucumber
+
+Cucumber is a test framework for creating plain english acceptance
+tests. The tests can be executed automatically. Cucumber is used for
+integration testing web applications. The test suite is often used in CI
+(Continuous Integration). Cucumber uses a language called Gherkin to
+parse files into lines and match them against regular expressions.
+Regular expressions are matched with code blocks. Your test code lives
+in these blocks.
+
+Cucumber tests are divided up into "Feature" files. Each feature has
+many "scenarios." Features are like use cases. Scenarios are different
+permutations of that use case. Here is an example Feature file:
+
+<pre>
+Feature: Make Widthdrawls from Accounts
+  As an account holder
+  I want to use my money
+  In order to use it buy thing
+
+  Background:
+    Given I have account under "RubyX"
+    And my account is activated
+
+  Scenario: There is enough money in my account
+    Given my account has "$1,000"
+    And I'm at the bank
+    When I widthdraw "$500"
+    Then my account should have "$500"
+
+  Scenario: There is not enough money in my account
+    Given my account has "$1,000"
+    And I'm at the bank
+    When I widthdraw "$500"
+    Then the teller should reject my transaction
+</pre>
+
+Here is an example step definition:
+
+<ruby>
+Given /I'm at the bank/ do
+  # set up pre conditions
+end
+
+Then /the teller should reject my transaction/ do
+  # assert on things
+end
+</ruby>
+
+h3. DSL
+
+DSL stands for Domain Specific Language. They are crafted to solve one
+or more problems very eloquently and nothing more. For example, a DSL
+created to declare work order would be horrible suited for writing
+Photoshop. DSLs are usually wrappers around more complicated methods
+that make it easier to express the intent of the underlying code from
+a programmer's perspective. You may have used a DSL before and 
+not realized it. Here is an example from Sunspot's search 
+functionality. It's designed for describing a search and nothing more:
+
+<ruby>
+Post.search do
+  fulltext 'best pizza'
+  with :blog_id, 1
+  with(:published_at).less_than Time.now
+  order_by :published_at, :desc
+  paginate :page => 2, :per_page => 15
+  facet :category_ids, :author_id
+end
+</ruby>
+
+h3. ERB
+
+ERB is Embedded Ruby. ERB is built into the Ruby core. It allows to to
+place Ruby inside other files. For example, placing Ruby inside HTML.
+Here is an example:
+
+<erb>
+<div class="<%= @ticket.state %>"
+  <p><%= @ticket.message %></p>
+</div>
+</erb>
+
+h3. Factories - FactoryGirl & Fabrication
+
+These are two popular libraries for creating object factories. They are
+usually used in test suites and population scripts. They provide a
+default set of attributes and allow programmers to specify the
+attributes they care about at creation time. Factories are commonly used
+to replace fixtures.
+
+h3. Fixtures
+
+Fixtures are static objects used in test cases. You may have a fixtures for specific
+test cases to build up needed preconditions. Fixtures are commonly used to represent
+data in a table. Fixtures are stored in YML and are loaded by a test library.
+Fixtures become hard to main at scale. They are often replaced with Factories because
+it's easier to generate an object at runtime then maintain a static file with its
+attributes.
+
+h3. Gem
+
+A gem is a resuable library of Ruby code. Gems are hosted on "RubyGems":http://rubygems.org.
+They are managed with the +gem+ command or with bundler. Rails is
+distributed as a gem.
+
+h3. Git
+
+Git is a distributed version control system. Each user has a complete
+copy of the repository. Changes can be pushed back to the remote
+repositories for others to pull or push from. Linus Torvalds created Git
+because he was unsatisfied with other version control systems like CVS
+or SVN. Do not get GitHub confused with Git. GitHub is simply a service
+for hosting the main Git repository. You can use git independent of
+github, however most Ruby developers use github exclusively.
+
+h3. HAML
+
+HAML is an HTML abstraction language. It's great for structuring
+documents and horrible to content. It will autoclose tags and lets you
+specify attributes as a hash. You can also include ruby code inside
+the templates. Here is an example:
+
+<pre>
+.post#post_5 
+  .content= simple_format(@post.content)
+</pre>
+
+h3. Heroku
+
+Ruby PaaS (Platform as a Service). They provide free cloud hosting for
+Rack applications with paid plans for increased resources. It is a very
+easy way to deploy your first application. Beware, they are easily owned
+by Amazon's AWS failure.
+
+h3. Integration Testing
+
+Integration testing referes testing different modules of code in concert.
+Ingration testing tests that all the parts of your system are working correctly.
+It is different than unit testing because it involves more than one component
+at at time. Integration tests for rails apps usually mean submitting web requests
+and see how they are handled. You can take this a step further and move into
+acceptance testing which simulates a user in front of your application. 
+Integration tests are written "outside in" meaning they only focus on 
+the outward functions of your system.
+
+h3. Less
+
+Less is a library for writing stylesheets. It enables you to do things
+like use variables and other handy things. Less files are compiled into
+vanilla CSS files. It is similar to SCSS/SASS. Twitter Bootstrap is written in Less.
+
+h3. Metaprogramming
+
+Metaprogramming is a term for dynamically generating code at runtime.
+Metaprogramming is why Rails feel the way it does. ActiveRecord
+associations to dynamically add methods to your classed based on how to
+declare them. Metaprogramming is possible in Ruby because it's a dynamic
+language interpreted at run time.
+
+h3. Nonrelational Databases (NoSQL)
+
+Nonrelational databases are the oppposte of relational databases. They
+are usually more free form and don't have defined schemas (like tables.)
+There is no such thing as SQL for non relational databases because each 
+one uses it's own langauge to inster and retreive data. MonogDB is 
+the most popular nonrelationable database.
+
+h3. Open Classes & Monkey Patching
+
+Ruby has open classes. This means you can simply declare methods insides
+a class that's already been defined. ActiveSupport uses open classes to
+add all those nice methods to core Ruby objects. This is how you can add
+a method to the `String` class:
+
+<ruby>
+class String
+  def lulz
+    puts "lulz " * self.length
+  end
+end
+
+"Hey".lulz
+</ruby>
+
+h3. ORM - Object Relational Mapping
+
+ORM's provide a way to map one object into some sort of persistent storage.
+ActiveRecord is a well known ORM that implements that Active Record pattern.
+ActiveRecord allows you persist objects into a relational database. ActiveRecord
+is not the only ORM. Datamapper and Sequel are also popular for relational databases.
+Mongoid is popular for MongoDB (a nonrelational database.)
+
+h3. Relational Databases
+
+Relational databases store data into tables with columns. Each column has a 
+type of data. For example: numbers, text, or dates. Data is retrieved
+using SQL. ORM's are commonly used to make it easier to work with data
+in retional databases. PostreSQL and MySQL are examples of popular
+realtional databases to use with Rails.
+
+h3. Rack
+
+Rack is a standard interface for writing web applications in Ruby.
+Rails as of version 3 is a Rack app. Rack defines things like HTTP requests
+and how your code is called. Rack applications are easily served by application
+servers such as Thin.
+
+h3. Rake
+
+Rake is like the Ruby version of make. You can create custom tasks that
+can be executed from the command line. `rake db:migrate` is a classic
+example. You can create as many tasks as you want. They can have
+prerequisites. They can also be in namespaces. A ':' designates tasks in
+different namespace. `db:migrate` means 'db' namespace, 'migrate' task.
+Multiple tasks can be executed in one go like so: `rake db:create
+schema:load`. They will be executed in the order they are listed. Rake
+was originally designed to be like make, but is often used to execute
+arbitrary code outside an application context. A cron job is a perfect
+example.
+
+h3. RSpec
+
+Rspec is a unit testing framework. It is based around the idea that test
+should describe behavior of classes in an english like way. Test files
+are called "specs". Spec files are divided into "examples." Examples
+contain matchers. Spec files can share examples. Here is an example
+spec_file:
+
+<ruby>
+require 'spec_helper'
+
+describe Post do
+  it { should have_many(:comments) }
+
+  describe "Post#out_dated?" do
+    subject { Post.new :created_at => 2.months.ago }
+
+    it { should be_outdated }
+  end
+end
+</ruby>
+
+h3. RVM
+
+Rvm stands for Ruby Version Manager. It is a set of bash script designed
+to allow you switch out Ruby interpreters on the fly. It manages
+installed ruby interpreters and makes is very easy to install different
+implementations. It also manages Gemsets. Gemsets are groups of gemsets
+that are distinct from other groups (except the global gemset which
+shares gems between different ruby interpreters).
+
+h3. Rbenv
+
+Rbenv was created to address some flaws in RVM. It does the same thing 
+as RVM in a different way. It allows you manage different Ruby versions
+and switch between them.
+
+h3. SASS & SCSS
+
+SASS and SCSS are CSS abstraction languages. They are compiled down to
+CSS. They allow you use variables, modules and include other files.
+In short, they make it much easier to write and main large amounts of
+CSS. 
+
+h3. SQL - Structured Query Language
+
+SQL is the standard language for talking to relational database. It's sole
+purpose is to describe what to get from the db, and now how to get it.
+SQL is based on simple concepts like selects and joins. You select columns
+from tables that you want back. You can define conditions to further refine
+your query or use joins to connect more than one table together.
+
+h3. Selenium
+
+Selenium is a library that simulates user interaction with a browser. It
+runs the full browser. Selenium works best in FireFox, but can work in
+Chrome and other browsers. Commands are sent across as JavaScript which
+the browser evaluates to complete each action. Selenium is the most
+complete solution for simulating a user for your web application.
+
+h3. Unit Testing
+
+Unit testing refers to testing small units of code insolation. This 
+makes it easier to determine if individual modules of code are functioning 
+directly. You can do unit testing with many different libraries. +Test::Unit+ 
+is the Rails default.
+
+h3. Test Driven Development (TDD)
+
+The practice of writing a failing test first then completing the
+implementation. This makes the developer spend more time thinking about
+the code upfront while providing a solid test suite for the entire
+application. You can use Test::Unit for TDD in Ruby.
+
+h3. Test::Unit
+
+Test::Unit is a unit test framework built into Ruby 1.8. It is known as
+MiniTest in 1.9. It provides functionality for writing test cases with
+standard setup and tear down. Rails generates test files built in
+Test::Unit by default. It provides basic assertions. It's similar to
+jUnit or any member of the xUnit family. Here is an example:
+
+<ruby>
+require 'test_helper'
+
+class PostTest < Test::Unit::TestCase 
+
+  def test_out_dated? do
+    post = Post.new :created_at => 2.months.ago
+    assertTrue(post.out_dated?)
+  end
+end
+</ruby>
+
+h3. UJS (Unobstrusive JavaScript)
+
+Unobtrusive JavaScript means separating JavaScript from the HTML.
+Specifying an `onClick` attribute in HTML is consider obtrusive because
+it obfuscates the markup. It is also hard to maintain because your
+javascript is harder to maintain. You can do the same thing
+unobtrusively by using jQuery to find the element by a class name and
+applying a click handler. Essentially UJS means keep JavaScript in .js
+files and HTML in .html files. Separation of church and state if you
+will.
+
+h3. Webrat
+
+Webrat is the original headless browser. It's similar to selenium, but
+much more implemented. It does not execute JavaScript and does not
+execute in a GUI. It is the most basic driver and is perfect for
+interacting with simple websites.