From 52e1a424980013b00a153b5221473e8fef73fac2 Mon Sep 17 00:00:00 2001 From: Tony Jian Date: Wed, 5 Dec 2012 02:39:49 +0800 Subject: [PATCH 01/21] add a notice about loading assets in production mode --- guides/source/asset_pipeline.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index fa4e714950..a4d6463035 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -100,7 +100,24 @@ In production, Rails precompiles these files to `public/assets` by default. The When you generate a scaffold or a controller, Rails also generates a JavaScript file (or CoffeeScript file if the `coffee-rails` gem is in the `Gemfile`) and a Cascading Style Sheet file (or SCSS file if `sass-rails` is in the `Gemfile`) for that controller. -For example, if you generate a `ProjectsController`, Rails will also add a new file at `app/assets/javascripts/projects.js.coffee` and another at `app/assets/stylesheets/projects.css.scss`. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as `<%= javascript_include_tag params[:controller] %>` or `<%= stylesheet_link_tag params[:controller] %>`. +For example, if you generate a `ProjectsController`, Rails will also add a new file at `app/assets/javascripts/projects.js.coffee` and another at `app/assets/stylesheets/projects.css.scss`. You should put any JavaScript or CSS unique to a controller inside their respective asset files, as these files can then be loaded just for these controllers with lines such as `<%= javascript_include_tag params[:controller] %>` or `<%= stylesheet_link_tag params[:controller] %>`. Note that you have to set `config.assets.precompile` in `config/environments/production.rb` if you want to precomepile them and use in production mode. You can append them one by one or do something like this: + + # config/environments/production.rb + config.assets.precompile << Proc.new { |path| + if path =~ /\.(css|js)\z/ + full_path = Rails.application.assets.resolve(path).to_path + app_assets_path = Rails.root.join('app', 'assets').to_path + if full_path.starts_with? app_assets_path + puts "including asset: " + full_path + true + else + puts "excluding asset: " + full_path + false + end + else + false + end + } NOTE: You must have an [ExecJS](https://github.com/sstephenson/execjs#readme) supported runtime in order to use CoffeeScript. If you are using Mac OS X or Windows you have a JavaScript runtime installed in your operating system. Check [ExecJS](https://github.com/sstephenson/execjs#readme) documentation to know all supported JavaScript runtimes. From ad223520bf8dca33ced04a0af279527da49489fc Mon Sep 17 00:00:00 2001 From: Pablo Torres Date: Tue, 4 Dec 2012 21:09:06 -0500 Subject: [PATCH 02/21] Correct bad English --- guides/source/getting_started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index b1ca8da292..17e9048c96 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -77,7 +77,7 @@ TIP: The examples below use # and $ to denote superuser and regular user termina Open up a command line prompt. On Mac OS X open Terminal.app, on Windows choose "Run" from your Start menu and type 'cmd.exe'. Any commands prefaced with a -dollar sign `$` should be run in the command line. Verify sure you have a +dollar sign `$` should be run in the command line. Verify that you have a current version of Ruby installed: ```bash @@ -101,7 +101,7 @@ To verify that you have everything installed correctly, you should be able to ru $ rails --version ``` -If it says something like "Rails 3.2.9" you are ready to continue. +If it says something like "Rails 3.2.9", you are ready to continue. ### Creating the Blog Application From cb389fc6d002b1ec9102f6d39d6de195dcf90c34 Mon Sep 17 00:00:00 2001 From: Pablo Torres Date: Tue, 4 Dec 2012 21:38:06 -0500 Subject: [PATCH 03/21] Define a generator before referring to it --- guides/source/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 17e9048c96..212a2a35f3 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -105,7 +105,7 @@ If it says something like "Rails 3.2.9", you are ready to continue. ### Creating the Blog Application -Rails comes with a number of generators that are designed to make your development life easier. One of these is the new application generator, which will provide you with the foundation of a Rails application so that you don't have to write it yourself. +Rails comes with a number of scripts called generators that are designed to make your development life easier by creating everything that's necessary to start working on a particular task. One of these is the new application generator, which will provide you with the foundation of a fresh Rails application so that you don't have to write it yourself. To use this generator, open a terminal, navigate to a directory where you have rights to create files, and type: From 83cb6fbd13f3c5ea3106b9a57964b1a6fb243682 Mon Sep 17 00:00:00 2001 From: Pablo Torres Date: Wed, 5 Dec 2012 21:39:58 -0500 Subject: [PATCH 04/21] Introduce Bundler and Gemfiles in a NOTE --- guides/source/getting_started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 212a2a35f3..db067ce62e 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -115,6 +115,8 @@ $ rails new blog This will create a Rails application called Blog in a directory called blog and install the gem dependencies that are already mentioned in `Gemfile` using `bundle install`. +NOTE: A Gemfile is a file that contains the list of all the gems that you require to run your application - the so called dependencies. With it, a program called Bundler can make sure that your machine has all of the requirements installed. This is the de facto way in Ruby to make sure that a machine is set up correctly to run a given program and Rails takes advantage of it to install some commonly-used gems. For more information, visit [Bundler's homepage](http://gembundler.com/). + TIP: You can see all of the command line options that the Rails application builder accepts by running `rails new -h`. From 7cf2912f062f5836d8fa772325411ab1e04715f2 Mon Sep 17 00:00:00 2001 From: Thiago Pinto Date: Thu, 6 Dec 2012 02:05:10 -0500 Subject: [PATCH 05/21] correct bad jquery syntax --- actionpack/lib/action_view/helpers/form_helper.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 17386a57b8..ce51585b87 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -775,8 +775,8 @@ module ActionView # text_field(:post, :title, class: "create_input") # # => # - # text_field(:session, :user, onchange: "if $('session[user]').value == 'admin' { alert('Your login can not be admin!'); }") - # # => + # text_field(:session, :user, onchange: "if $('#session_user').value == 'admin' { alert('Your login can not be admin!'); }") + # # => # # text_field(:snippet, :code, size: 20, class: 'code_input') # # => From 4aced1f0730896128e9b8d68f9cacc00328b31ec Mon Sep 17 00:00:00 2001 From: Thiago Pinto Date: Thu, 6 Dec 2012 02:13:33 -0500 Subject: [PATCH 06/21] adding example for f.file_input --- actionpack/lib/action_view/helpers/form_helper.rb | 3 +++ 1 file changed, 3 insertions(+) diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index ce51585b87..be62cf70c6 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -834,6 +834,9 @@ module ActionView # file_field(:user, :avatar) # # => # + # file_field(:post, :image, :multiple => true) + # # => + # # file_field(:post, :attached, accept: 'text/html') # # => # From 15f26631062ae7258e0ebd1ef128a88f59def760 Mon Sep 17 00:00:00 2001 From: Thiago Pinto Date: Thu, 6 Dec 2012 02:21:15 -0500 Subject: [PATCH 07/21] adding example for f.file_input --- actionpack/lib/action_view/helpers/form_helper.rb | 3 +++ 1 file changed, 3 insertions(+) diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index be62cf70c6..92b88752d4 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -840,6 +840,9 @@ module ActionView # file_field(:post, :attached, accept: 'text/html') # # => # + # file_field(:post, :image, accept: 'image/png,image/gif,image/jpeg') + # # => + # # file_field(:attachment, :file, class: 'file_input') # # => def file_field(object_name, method, options = {}) From d2fb5f2ae6bfe636505d0003fd2c760f4df8151a Mon Sep 17 00:00:00 2001 From: Thiago Pinto Date: Thu, 6 Dec 2012 02:33:43 -0500 Subject: [PATCH 08/21] complementary options guidelines for f.file_field and file_field_tag --- actionpack/lib/action_view/helpers/form_helper.rb | 6 ++++++ actionpack/lib/action_view/helpers/form_tag_helper.rb | 2 ++ 2 files changed, 8 insertions(+) diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 92b88752d4..5710d1fc02 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -830,6 +830,12 @@ module ActionView # # Using this method inside a +form_for+ block will set the enclosing form's encoding to multipart/form-data. # + # ==== Options + # * Creates standard HTML attributes for the tag. + # * :disabled - If set to true, the user will not be able to use this input. + # * :multiple - If set to true, *in most updated browsers* the user will be allowed to select multiple files. + # * :accept - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations. + # # ==== Examples # file_field(:user, :avatar) # # => diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index e298751062..ff83ef3ca1 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -233,6 +233,8 @@ module ActionView # ==== Options # * Creates standard HTML attributes for the tag. # * :disabled - If set to true, the user will not be able to use this input. + # * :multiple - If set to true, *in most updated browsers* the user will be allowed to select multiple files. + # * :accept - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations. # # ==== Examples # file_field_tag 'attachment' From ba2d867b2961b5ef72aad353c2d647b04654cbe3 Mon Sep 17 00:00:00 2001 From: Thiago Pinto Date: Thu, 6 Dec 2012 02:52:40 -0500 Subject: [PATCH 09/21] API reader should look elsewhere for helper instructions --- .../lib/action_view/helpers/form_helper.rb | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 5710d1fc02..f0abb79bd0 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -1226,6 +1226,10 @@ module ActionView RUBY_EVAL end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def fields_for(record_name, record_object = nil, fields_options = {}, &block) fields_options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options? fields_options[:builder] ||= options[:builder] @@ -1255,23 +1259,43 @@ module ActionView @template.fields_for(record_name, record_object, fields_options, &block) end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def label(method, text = nil, options = {}, &block) @template.label(@object_name, method, text, objectify_options(options), &block) end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def check_box(method, options = {}, checked_value = "1", unchecked_value = "0") @template.check_box(@object_name, method, objectify_options(options), checked_value, unchecked_value) end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def radio_button(method, tag_value, options = {}) @template.radio_button(@object_name, method, tag_value, objectify_options(options)) end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def hidden_field(method, options = {}) @emitted_hidden_id = true if method == :id @template.hidden_field(@object_name, method, objectify_options(options)) end + # Instructions for this +method+ can be found in this documentation. + # For reusability and delegation reasons, various +methods+ have equal names. + # Please, look up the next +method+ with this name + # def file_field(method, options = {}) self.multipart = true @template.file_field(@object_name, method, objectify_options(options)) From 4bdbf0a4a62e831d1ad9ccf7f77f7dd6f8fb2044 Mon Sep 17 00:00:00 2001 From: Drew Dara-Abrams Date: Thu, 6 Dec 2012 16:04:53 -0800 Subject: [PATCH 10/21] changing tense, since Rails 3.2 has been released --- guides/source/active_record_querying.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 9620270141..b22cc09951 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1222,7 +1222,7 @@ You can specify an exclamation point (`!`) on the end of the dynamic finders to If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`. -WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior will be changed in Rails 3.2 to throw an `ArgumentError`. +WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior has been changed in Rails 3.2 to throw an `ArgumentError`. Find or build a new object -------------------------- From 70b809436fdc4f4f95155b0e5968e6cd10b80cd0 Mon Sep 17 00:00:00 2001 From: "Ian C. Anderson" Date: Fri, 7 Dec 2012 12:00:48 -0500 Subject: [PATCH 11/21] Added overview items to Guides Guidelines prologue --- guides/source/ruby_on_rails_guides_guidelines.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/guides/source/ruby_on_rails_guides_guidelines.md b/guides/source/ruby_on_rails_guides_guidelines.md index 2c3bc686ef..5031a1b531 100644 --- a/guides/source/ruby_on_rails_guides_guidelines.md +++ b/guides/source/ruby_on_rails_guides_guidelines.md @@ -5,6 +5,9 @@ This guide documents guidelines for writing Ruby on Rails Guides. This guide fol After reading this guide, you will know: +* Standards for writing and formatting rails guide source files +* How to generate HTML documentation from source files + -------------------------------------------------------------------------------- Markdown From 7c05ea23a0e6394c61f3d2c1d0ba345784329427 Mon Sep 17 00:00:00 2001 From: Katie Oldaker Date: Fri, 7 Dec 2012 12:50:09 -0500 Subject: [PATCH 12/21] Fixed grammar in a lot of guide prologues. --- guides/source/action_controller_overview.md | 14 +++++++------- guides/source/active_record_callbacks.md | 8 ++++---- guides/source/active_record_querying.md | 14 +++++++------- guides/source/active_record_validations.md | 6 +++--- guides/source/asset_pipeline.md | 10 +++++----- guides/source/association_basics.md | 6 +++--- guides/source/command_line.md | 10 +++++----- guides/source/configuring.md | 4 ++-- guides/source/contributing_to_ruby_on_rails.md | 10 +++++----- guides/source/debugging_rails_applications.md | 8 ++++---- guides/source/form_helpers.md | 14 +++++++------- guides/source/generators.md | 14 +++++++------- guides/source/getting_started.md | 2 +- guides/source/initialization.md | 2 +- guides/source/layouts_and_rendering.md | 8 ++++---- guides/source/performance_testing.md | 10 +++++----- guides/source/plugins.md | 4 ++-- guides/source/rails_application_templates.md | 4 ++-- guides/source/rails_on_rack.md | 8 ++++---- guides/source/routing.md | 10 +++++----- guides/source/testing.md | 6 +++--- guides/source/working_with_javascript_in_rails.md | 4 ++-- 22 files changed, 88 insertions(+), 88 deletions(-) diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 69d99becb9..dc672647cc 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -5,13 +5,13 @@ In this guide you will learn how controllers work and how they fit into the requ After reading this guide, you will know: -* Follow the flow of a request through a controller. -* Understand why and how to store data in the session or cookies. -* Work with filters to execute code during request processing. -* Use Action Controller's built-in HTTP authentication. -* Stream data directly to the user's browser. -* Filter sensitive parameters so they do not appear in the application's log. -* Deal with exceptions that may be raised during request processing. +* How to follow the flow of a request through a controller. +* Why and how to store data in the session or cookies. +* How to work with filters to execute code during request processing. +* How to use Action Controller's built-in HTTP authentication. +* How to stream data directly to the user's browser. +* How to filter sensitive parameters so they do not appear in the application's log. +* How to deal with exceptions that may be raised during request processing. -------------------------------------------------------------------------------- diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index c45f3f2e6a..550800861d 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -4,11 +4,11 @@ Active Record Callbacks This guide teaches you how to hook into the life cycle of your Active Record objects. -After reading this guide and trying out the presented concepts, we hope that you'll be able to: +After reading this guide, you will know: -* Understand the life cycle of Active Record objects -* Create callback methods that respond to events in the object life cycle -* Create special classes that encapsulate common behavior for your callbacks +* The life cycle of Active Record objects. +* How to create callback methods that respond to events in the object life cycle. +* How to create special classes that encapsulate common behavior for your callbacks. -------------------------------------------------------------------------------- diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index b22cc09951..4ee6374175 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -5,13 +5,13 @@ This guide covers different ways to retrieve data from the database using Active After reading this guide, you will know: -* Find records using a variety of methods and conditions. -* Specify the order, retrieved attributes, grouping, and other properties of the found records. -* Use eager loading to reduce the number of database queries needed for data retrieval. -* Use dynamic finders methods. -* Check for the existence of particular records. -* Perform various calculations on Active Record models. -* Run EXPLAIN on relations. +* How to find records using a variety of methods and conditions. +* How to specify the order, retrieved attributes, grouping, and other properties of the found records. +* How to use eager loading to reduce the number of database queries needed for data retrieval. +* How to use dynamic finders methods. +* How to check for the existence of particular records. +* How to perform various calculations on Active Record models. +* How to run EXPLAIN on relations. -------------------------------------------------------------------------------- diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index e752c6f3f9..f8cc759d9c 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -6,9 +6,9 @@ the database using Active Record's validations feature. After reading this guide, you will know: -* Use the built-in Active Record validation helpers -* Create your own custom validation methods -* Work with the error messages generated by the validation process +* How to use the built-in Active Record validation helpers. +* How to create your own custom validation methods. +* How to work with the error messages generated by the validation process. -------------------------------------------------------------------------------- diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index a4d6463035..a00d019cc1 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -5,11 +5,11 @@ This guide covers the asset pipeline introduced in Rails 3.1. After reading this guide, you will know: -* Understand what the asset pipeline is and what it does. -* Properly organize your application assets. -* Understand the benefits of the asset pipeline. -* Add a pre-processor to the pipeline. -* Package assets with a gem. +* How to understand what the asset pipeline is and what it does. +* How to properly organize your application assets. +* How to understand the benefits of the asset pipeline. +* How to add a pre-processor to the pipeline. +* How to package assets with a gem. -------------------------------------------------------------------------------- diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 43d3b20165..2f407c603d 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -5,9 +5,9 @@ This guide covers the association features of Active Record. After reading this guide, you will know: -* Declare associations between Active Record models. -* Understand the various types of Active Record associations. -* Use the methods added to your models by creating associations. +* How to declare associations between Active Record models. +* How to understand the various types of Active Record associations. +* How to use the methods added to your models by creating associations. -------------------------------------------------------------------------------- diff --git a/guides/source/command_line.md b/guides/source/command_line.md index 0a4a704cd9..746226fa96 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -5,11 +5,11 @@ Rails comes with every command line tool you'll need to After reading this guide, you will know: -* Create a Rails application. -* Generate models, controllers, database migrations, and unit tests. -* Start a development server. -* Experiment with objects through an interactive shell. -* Profile and benchmark your new creation. +* How to create a Rails application. +* How to generate models, controllers, database migrations, and unit tests. +* How to start a development server. +* How to experiment with objects through an interactive shell. +* How to profile and benchmark your new creation. -------------------------------------------------------------------------------- diff --git a/guides/source/configuring.md b/guides/source/configuring.md index dba2be3b71..eae0f5b641 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -5,8 +5,8 @@ This guide covers the configuration and initialization features available to Rai After reading this guide, you will know: -* Adjust the behavior of your Rails applications. -* Add additional code to be run at application start time. +* How to adjust the behavior of your Rails applications. +* How to add additional code to be run at application start time. -------------------------------------------------------------------------------- diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index fa6c335088..1e0cb6ee4a 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -5,11 +5,11 @@ This guide covers ways in which _you_ can become a part of the ongoing developme After reading this guide, you will know: -* Using GitHub to report issues. -* Cloning master and running the test suite. -* Helping to resolve existing issues. -* Contributing to the Ruby on Rails documentation. -* Contributing to the Ruby on Rails code. +* How to use GitHub to report issues. +* How to clone master and run the test suite. +* How to help resolve existing issues. +* How to contribute to the Ruby on Rails documentation. +* How to contribute to the Ruby on Rails code. Ruby on Rails is not "someone else's framework." Over the years, hundreds of people have contributed to Ruby on Rails ranging from a single character to massive architectural changes or significant documentation — all with the goal of making Ruby on Rails better for everyone. Even if you don't feel up to writing code or documentation yet, there are a variety of other ways that you can contribute, from reporting issues to testing patches. diff --git a/guides/source/debugging_rails_applications.md b/guides/source/debugging_rails_applications.md index 96112da50f..addc3a63a8 100644 --- a/guides/source/debugging_rails_applications.md +++ b/guides/source/debugging_rails_applications.md @@ -5,10 +5,10 @@ This guide introduces techniques for debugging Ruby on Rails applications. After reading this guide, you will know: -* Understand the purpose of debugging. -* Track down problems and issues in your application that your tests aren't identifying. -* Learn the different ways of debugging. -* Analyze the stack trace. +* The purpose of debugging. +* How to track down problems and issues in your application that your tests aren't identifying. +* The different ways of debugging. +* How to analyze the stack trace. -------------------------------------------------------------------------------- diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index b89d776d87..d22b2f8ef6 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -5,13 +5,13 @@ Forms in web applications are an essential interface for user input. However, fo After reading this guide, you will know: -* Create search forms and similar kind of generic forms not representing any specific model in your application. -* Make model-centric forms for creation and editing of specific database records. -* Generate select boxes from multiple types of data. -* Understand the date and time helpers Rails provides. -* Learn what makes a file upload form different. -* Learn some cases of building forms to external resources. -* Find out how to build complex forms. +* How to create search forms and similar kind of generic forms not representing any specific model in your application. +* How to make model-centric forms for creation and editing of specific database records. +* How to generate select boxes from multiple types of data. +* The date and time helpers Rails provides. +* What makes a file upload form different. +* Some cases of building forms to external resources. +* How to build complex forms. -------------------------------------------------------------------------------- diff --git a/guides/source/generators.md b/guides/source/generators.md index f83f5c6691..d23110edd6 100644 --- a/guides/source/generators.md +++ b/guides/source/generators.md @@ -5,13 +5,13 @@ Rails generators are an essential tool if you plan to improve your workflow. Wit After reading this guide, you will know: -* Learn how to see which generators are available in your application. -* Create a generator using templates. -* Learn how Rails searches for generators before invoking them. -* Customize your scaffold by creating new generators. -* Customize your scaffold by changing generator templates. -* Learn how to use fallbacks to avoid overwriting a huge set of generators. -* Learn how to create an application template. +* How to see which generators are available in your application. +* How to create a generator using templates. +* How Rails searches for generators before invoking them. +* How to customize your scaffold by creating new generators. +* How to customize your scaffold by changing generator templates. +* How to use fallbacks to avoid overwriting a huge set of generators. +* How to create an application template. -------------------------------------------------------------------------------- diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index db067ce62e..37760e4393 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -5,7 +5,7 @@ This guide covers getting up and running with Ruby on Rails. After reading this guide, you will know: -* Installing Rails, creating a new Rails application, and connecting your +* How to install Rails, create a new Rails application, and connect your application to a database. * The general layout of a Rails application. * The basic principles of MVC (Model, View, Controller) and RESTful design. diff --git a/guides/source/initialization.md b/guides/source/initialization.md index 6a34125654..32df508f9c 100644 --- a/guides/source/initialization.md +++ b/guides/source/initialization.md @@ -6,7 +6,7 @@ as of Rails 4. It is an extremely in-depth guide and recommended for advanced Ra After reading this guide, you will know: -* Using `rails server`. +* How to use `rails server`. -------------------------------------------------------------------------------- diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index 394ef794d3..b23ae04380 100644 --- a/guides/source/layouts_and_rendering.md +++ b/guides/source/layouts_and_rendering.md @@ -5,10 +5,10 @@ This guide covers the basic layout features of Action Controller and Action View After reading this guide, you will know: -* Use the various rendering methods built into Rails. -* Create layouts with multiple content sections. -* Use partials to DRY up your views. -* Use nested layouts (sub-templates). +* How to use the various rendering methods built into Rails. +* How to create layouts with multiple content sections. +* How to use partials to DRY up your views. +* How to use nested layouts (sub-templates). -------------------------------------------------------------------------------- diff --git a/guides/source/performance_testing.md b/guides/source/performance_testing.md index a07f64ec29..182f7eb0fd 100644 --- a/guides/source/performance_testing.md +++ b/guides/source/performance_testing.md @@ -6,12 +6,12 @@ application. After reading this guide, you will know: -* Understand the various types of benchmarking and profiling metrics. -* Generate performance and benchmarking tests. -* Install and use a GC-patched Ruby binary to measure memory usage and object +* The various types of benchmarking and profiling metrics. +* How to generate performance and benchmarking tests. +* How to install and use a GC-patched Ruby binary to measure memory usage and object allocation. -* Understand the benchmarking information provided by Rails inside the log files. -* Learn about various tools facilitating benchmarking and profiling. +* The benchmarking information provided by Rails inside the log files. +* Various tools facilitating benchmarking and profiling. Performance testing is an integral part of the development cycle. It is very important that you don't make your end users wait for too long before the page diff --git a/guides/source/plugins.md b/guides/source/plugins.md index c7c843ec3a..42746e34d7 100644 --- a/guides/source/plugins.md +++ b/guides/source/plugins.md @@ -9,8 +9,8 @@ A Rails plugin is either an extension or a modification of the core framework. P After reading this guide, you will know: -* Creating a plugin from scratch. -* Writing and running tests for the plugin. +* How to create a plugin from scratch. +* How to write and run tests for the plugin. This guide describes how to build a test-driven plugin that will: diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index 83c563ac78..9e694acb98 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -5,8 +5,8 @@ Application templates are simple Ruby files containing DSL for adding gems/initi After reading this guide, you will know: -* Use templates to generate/customize Rails applications. -* Write your own reusable application templates using the Rails template API. +* How to use templates to generate/customize Rails applications. +* How to write your own reusable application templates using the Rails template API. -------------------------------------------------------------------------------- diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md index 531b35a973..1fac6d9883 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -5,10 +5,10 @@ This guide covers Rails integration with Rack and interfacing with other Rack co After reading this guide, you will know: -* Create Rails Metal applications. -* Use Rack Middlewares in your Rails applications. -* Understand Action Pack's internal Middleware stack. -* Define a custom Middleware stack. +* How to create Rails Metal applications. +* How to use Rack Middlewares in your Rails applications. +* Action Pack's internal Middleware stack. +* How to define a custom Middleware stack. -------------------------------------------------------------------------------- diff --git a/guides/source/routing.md b/guides/source/routing.md index 714c0b609e..0e78e7d4cd 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -5,11 +5,11 @@ This guide covers the user-facing features of Rails routing. After reading this guide, you will know: -* Understand the code in `routes.rb`. -* Construct your own routes, using either the preferred resourceful style or the `match` method. -* Identify what parameters to expect an action to receive. -* Automatically create paths and URLs using route helpers. -* Use advanced techniques such as constraints and Rack endpoints. +* How to interpret the code in `routes.rb`. +* How to construct your own routes, using either the preferred resourceful style or the `match` method. +* What parameters to expect an action to receive. +* How to automatically create paths and URLs using route helpers. +* Advanced techniques such as constraints and Rack endpoints. -------------------------------------------------------------------------------- diff --git a/guides/source/testing.md b/guides/source/testing.md index 9ce94f4c53..a9bce04522 100644 --- a/guides/source/testing.md +++ b/guides/source/testing.md @@ -6,9 +6,9 @@ application. After reading this guide, you will know: -* Understand Rails testing terminology. -* Write unit, functional, and integration tests for your application. -* Identify other popular testing approaches and plugins. +* Rails testing terminology. +* How to write unit, functional, and integration tests for your application. +* Other popular testing approaches and plugins. -------------------------------------------------------------------------------- diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md index 26e3403ff9..0f5acfba3c 100644 --- a/guides/source/working_with_javascript_in_rails.md +++ b/guides/source/working_with_javascript_in_rails.md @@ -7,10 +7,10 @@ ease! After reading this guide, you will know: -* Quick introduction to Ajax. +* The basics of Ajax. * Unobtrusive JavaScript. * How Rails' built-in helpers assist you. -* Handling Ajax on the server side. +* How to handle Ajax on the server side. * The Turbolinks gem. ------------------------------------------------------------------------------- From 38db4e2ca9902a57ae45422cba9cccbfc3e912b6 Mon Sep 17 00:00:00 2001 From: Max Katz Date: Fri, 7 Dec 2012 10:57:24 -0700 Subject: [PATCH 13/21] Fix small grammatical error --- guides/source/action_controller_overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index dc672647cc..a97159b653 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -836,7 +836,7 @@ class DinnerController end ``` -Just like the filter, you could also passing `:only` and `:except` to enforce the secure connection only to specific actions: +Just like the filter, you could also pass `:only` and `:except` to enforce the secure connection only to specific actions: ```ruby class DinnerController From fc6336d1bed794681b09cc10c80182cd457fb414 Mon Sep 17 00:00:00 2001 From: Katie Oldaker Date: Fri, 7 Dec 2012 16:31:27 -0500 Subject: [PATCH 14/21] Punctuation, capitalization, grammar fixes in rails guides --- guides/source/action_mailer_basics.md | 4 ++++ guides/source/active_record_querying.md | 4 ++-- guides/source/active_record_validations.md | 4 ++-- guides/source/asset_pipeline.md | 10 +++++----- guides/source/association_basics.md | 2 +- guides/source/contributing_to_ruby_on_rails.md | 4 ++-- guides/source/migrations.md | 6 +++--- 7 files changed, 19 insertions(+), 15 deletions(-) diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index ddb0e438c9..03e3cab0c7 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -5,6 +5,10 @@ This guide should provide you with all you need to get started in sending and re After reading this guide, you will know: +* How to send and receive email within a Rails application. +* How to generate and edit an Action Mailer class and mailer view. +* How to configure Action Mailer for your environment. +* How to test your Action Mailer classes. -------------------------------------------------------------------------------- Introduction diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 4ee6374175..641a2f8fc0 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1190,7 +1190,7 @@ class Client < ActiveRecord::Base end ``` -### Removing all scoping +### Removing All Scoping If we wish to remove scoping for any reason we can use the `unscoped` method. This is especially useful if a `default_scope` is specified in the model and should not be @@ -1224,7 +1224,7 @@ If you want to find both by name and locked, you can chain these finders togethe WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior has been changed in Rails 3.2 to throw an `ArgumentError`. -Find or build a new object +Find or Build a New Object -------------------------- It's common that you need to find a record or create it if it doesn't exist. You can do that with the `find_or_create_by` and `find_or_create_by!` methods. diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index f8cc759d9c..6e20e74c34 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -779,7 +779,7 @@ class Account < ActiveRecord::Base end ``` -### Grouping conditional validations +### Grouping Conditional validations Sometimes it is useful to have multiple validations use one condition, it can be easily achieved using `with_options`. @@ -796,7 +796,7 @@ end All validations inside of `with_options` block will have automatically passed the condition `if: :is_admin?` -### Combining validation conditions +### Combining Validation Conditions On the other hand, when multiple conditions define whether or not a validation should happen, an `Array` can be used. Moreover, you can apply both `:if` and diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index a00d019cc1..ee79d291d3 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -131,7 +131,7 @@ Pipeline assets can be placed inside an application in one of three locations: ` * `vendor/assets` is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks. -#### Search paths +#### Search Paths When a file is referenced from a manifest or a helper, Sprockets searches the three default asset locations for it. @@ -179,7 +179,7 @@ Paths are traversed in the order that they occur in the search path. By default, It is important to note that files you want to reference outside a manifest must be added to the precompile array or they will not be available in the production environment. -#### Using index files +#### Using Index Files Sprockets uses files named `index` (with the relevant extensions) for a special purpose. @@ -354,7 +354,7 @@ would generate this HTML: The `body` param is required by Sprockets. -### Turning Debugging off +### Turning Debugging Off You can turn off debug mode by updating `config/environments/development.rb` to include: @@ -479,7 +479,7 @@ The default location for the manifest is the root of the location specified in ` NOTE: If there are missing precompiled files in production you will get an `Sprockets::Helpers::RailsHelper::AssetPaths::AssetNotPrecompiledError` exception indicating the name of the missing file(s). -#### Far-future Expires header +#### Far-future Expires Header Precompiled assets exist on the filesystem and are served directly by your web server. They do not have far-future headers by default, so to get the benefit of fingerprinting you'll have to update your server configuration to add them. @@ -509,7 +509,7 @@ location ~ ^/assets/ { } ``` -#### GZip compression +#### GZip Compression When files are precompiled, Sprockets also creates a [gzipped](http://en.wikipedia.org/wiki/Gzip) (.gz) version of your assets. Web servers are typically configured to use a moderate compression ratio as a compromise, but since precompilation happens once, Sprockets uses the maximum compression ratio, thus reducing the size of the data transfer to the minimum. On the other hand, web servers can be configured to serve compressed content directly from disk, rather than deflating non-compressed files themselves. diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 2f407c603d..95adb4ff0a 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -452,7 +452,7 @@ class CreateAssemblyPartJoinTable < ActiveRecord::Migration end ``` -We pass `id: false` to `create_table` because that table does not represent a model. That's required for the association to work properly. If you observe any strange behavior in a `has_and_belongs_to_many` association like mangled models IDs, or exceptions about conflicting IDs chances are you forgot that bit. +We pass `id: false` to `create_table` because that table does not represent a model. That's required for the association to work properly. If you observe any strange behavior in a `has_and_belongs_to_many` association like mangled models IDs, or exceptions about conflicting IDs, chances are you forgot that bit. ### Controlling Association Scope diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 1e0cb6ee4a..ce2a5a4902 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -91,7 +91,7 @@ You can invoke `test_jdbcmysql`, `test_jdbcsqlite3` or `test_jdbcpostgresql` als The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. -As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: +As of this writing (December, 2010) they are especially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: ```bash $ RUBYOPT=-W0 bundle exec rake test @@ -205,7 +205,7 @@ TIP: Changes that are cosmetic in nature and do not add anything substantial to ### Follow the Coding Conventions -Rails follows a simple set of coding style conventions. +Rails follows a simple set of coding style conventions: * Two spaces, no tabs (for indentation). * No trailing whitespace. Blank lines should not have any spaces. diff --git a/guides/source/migrations.md b/guides/source/migrations.md index 829cbf2873..9840e7694f 100644 --- a/guides/source/migrations.md +++ b/guides/source/migrations.md @@ -334,7 +334,7 @@ end removes the `description` and `name` columns, creates a `part_number` string column and adds an index on it. Finally it renames the `upccode` column. -### When Helpers Aren't Enough +### When Helpers aren't Enough If the helpers provided by Active Record aren't enough you can use the `execute` method to execute arbitrary SQL: @@ -585,8 +585,8 @@ Occasionally you will make a mistake when writing a migration. If you have already run the migration then you cannot just edit the migration and run the migration again: Rails thinks it has already run the migration and so will do nothing when you run `rake db:migrate`. You must rollback the migration (for -example with `rake db:rollback`), edit your migration and then run `rake -db:migrate` to run the corrected version. +example with `rake db:rollback`), edit your migration and then run +`rake db:migrate` to run the corrected version. In general, editing existing migrations is not a good idea. You will be creating extra work for yourself and your co-workers and cause major headaches From e618adbcabe59eaccfab1f721eb3cf1e915e012e Mon Sep 17 00:00:00 2001 From: "Claudio B." Date: Fri, 7 Dec 2012 16:54:32 -0800 Subject: [PATCH 15/21] Update activesupport/lib/active_support/deprecation/proxy_wrappers.rb Fix a typo in rdoc (*expect* for *except*) --- activesupport/lib/active_support/deprecation/proxy_wrappers.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb index 17e69c34a5..485dc91063 100644 --- a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb +++ b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb @@ -30,7 +30,7 @@ module ActiveSupport # @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!") # @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!", deprecator_instance) # - # When someone execute any method expect +inspect+ on proxy object this will + # When someone executes any method except +inspect+ on proxy object this will # trigger +warn+ method on +deprecator_instance+. # # Default deprecator is ActiveSupport::Deprecation From ed78770b1a13788a5d3fcae484f34654de580bd5 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 7 Dec 2012 23:20:35 -0800 Subject: [PATCH 16/21] Remove references to Rails versions. There's no reason for guides to reference old behaviors. They should be current as of the versions of Rails that they ship with, and including older information just clutters thing. I discussed this change with @fxn and he agrees. --- guides/source/action_controller_overview.md | 2 +- guides/source/action_mailer_basics.md | 4 +--- guides/source/action_view_overview.md | 4 +--- guides/source/active_record_querying.md | 2 -- .../source/active_support_core_extensions.md | 8 +++---- guides/source/asset_pipeline.md | 10 +++----- guides/source/configuring.md | 4 +--- guides/source/engines.md | 2 +- guides/source/form_helpers.md | 2 -- guides/source/generators.md | 2 -- guides/source/layouts_and_rendering.md | 23 +++---------------- guides/source/plugins.md | 5 +--- guides/source/routing.md | 6 ----- 13 files changed, 15 insertions(+), 59 deletions(-) diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index a97159b653..f17f850107 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -828,7 +828,7 @@ NOTE: Certain exceptions are only rescuable from the `ApplicationController` cla Force HTTPS protocol -------------------- -Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. Since Rails 3.1 you can now use the `force_ssl` method in your controller to enforce that: +Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. You can use the `force_ssl` method in your controller to enforce that: ```ruby class DinnerController diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 03e3cab0c7..9411ac7325 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -109,7 +109,7 @@ When you call the `mail` method now, Action Mailer will detect the two templates #### Wire It Up So That the System Sends the Email When a User Signs Up -There are several ways to do this, some people create Rails Observers to fire off emails, others do it inside of the User Model. However, in Rails 3, mailers are really just another way to render a view. Instead of rendering a view and sending out the HTTP protocol, they are just sending it out through the Email protocols instead. Due to this, it makes sense to just have your controller tell the mailer to send an email when a user is successfully created. +There are several ways to do this, some people create Rails Observers to fire off emails, others do it inside of the User Model. However, mailers are really just another way to render a view. Instead of rendering a view and sending out the HTTP protocol, they are just sending it out through the Email protocols instead. Due to this, it makes sense to just have your controller tell the mailer to send an email when a user is successfully created. Setting this up is painfully simple. @@ -149,8 +149,6 @@ This provides a much simpler implementation that does not require the registerin The method `welcome_email` returns a `Mail::Message` object which can then just be told `deliver` to send itself out. -NOTE: In previous versions of Rails, you would call `deliver_welcome_email` or `create_welcome_email`. This has been deprecated in Rails 3.0 in favour of just calling the method name itself. - WARNING: Sending out an email should only take a fraction of a second. If you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job. ### Auto encoding header values diff --git a/guides/source/action_view_overview.md b/guides/source/action_view_overview.md index c931b30bd3..4ea60391ba 100644 --- a/guides/source/action_view_overview.md +++ b/guides/source/action_view_overview.md @@ -1263,10 +1263,8 @@ Creates a field set for grouping HTML form elements. Creates a file upload field. -Prior to Rails 3.1, if you are using file uploads, then you will need to set the multipart option for the form tag. Rails 3.1+ does this automatically. - ```html+erb -<%= form_tag {action: "post"}, {multipart: true} do %> +<%= form_tag {action: "post"} do %> <%= file_field_tag "file" %> <%= submit_tag %> <% end %> diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 641a2f8fc0..889e869a2a 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1222,8 +1222,6 @@ You can specify an exclamation point (`!`) on the end of the dynamic finders to If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`. -WARNING: Up to and including Rails 3.1, when the number of arguments passed to a dynamic finder method is lesser than the number of fields, say `Client.find_by_name_and_locked("Ryan")`, the behavior is to pass `nil` as the missing argument. This is **unintentional** and this behavior has been changed in Rails 3.2 to throw an `ArgumentError`. - Find or Build a New Object -------------------------- diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 775da2a85c..666e9ee201 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -1120,8 +1120,6 @@ C.subclasses # => [B, D] The order in which these classes are returned is unspecified. -WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1. - NOTE: Defined in `active_support/core_ext/class/subclasses.rb`. #### `descendants` @@ -1157,7 +1155,7 @@ Inserting data into HTML templates needs extra care. For example, you can't just #### Safe Strings -Active Support has the concept of (html) safe strings since Rails 3. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not. +Active Support has the concept of (html) safe strings. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not. Strings are considered to be unsafe by default: @@ -1194,10 +1192,10 @@ Safe arguments are directly appended: "".html_safe + "<".html_safe # => "<" ``` -These methods should not be used in ordinary views. In Rails 3 unsafe values are automatically escaped: +These methods should not be used in ordinary views. Unsafe values are automatically escaped: ```erb -<%= @review.title %> <%# fine in Rails 3, escaped if needed %> +<%= @review.title %> <%# fine, escaped if needed %> ``` To insert something verbatim use the `raw` helper rather than calling `html_safe`: diff --git a/guides/source/asset_pipeline.md b/guides/source/asset_pipeline.md index ee79d291d3..ff6787dae5 100644 --- a/guides/source/asset_pipeline.md +++ b/guides/source/asset_pipeline.md @@ -1,7 +1,7 @@ The Asset Pipeline ================== -This guide covers the asset pipeline introduced in Rails 3.1. +This guide covers the asset pipeline. After reading this guide, you will know: @@ -18,11 +18,9 @@ What is the Asset Pipeline? The asset pipeline provides a framework to concatenate and minify or compress JavaScript and CSS assets. It also adds the ability to write these assets in other languages such as CoffeeScript, Sass and ERB. -Prior to Rails 3.1 these features were added through third-party Ruby libraries such as Jammit and Sprockets. Rails 3.1 is integrated with Sprockets through Action Pack which depends on the `sprockets` gem, by default. - Making the asset pipeline a core feature of Rails means that all developers can benefit from the power of having their assets pre-processed, compressed and minified by one central library, Sprockets. This is part of Rails' "fast by default" strategy as outlined by DHH in his keynote at RailsConf 2011. -In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in `config/application.rb` by putting this line inside the application class definition: +The asset pipeline is enabled by default. It can be disabled in `config/application.rb` by putting this line inside the application class definition: ```ruby config.assets.enabled = false @@ -287,8 +285,6 @@ For example, a new Rails application includes a default `app/assets/javascripts/ In JavaScript files, the directives begin with `//=`. In this case, the file is using the `require` and the `require_tree` directives. The `require` directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files `jquery.js` and `jquery_ujs.js` that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a `.js` file when done from within a `.js` file. -NOTE. In Rails 3.1 the `jquery-rails` gem provides the `jquery.js` and `jquery_ujs.js` files via the asset pipeline. You won't see them in the application tree. - The `require_tree` directive tells Sprockets to recursively include _all_ JavaScript files in the specified directory into the output. These paths must be specified relative to the manifest file. You can also use the `require_directory` directive which includes all JavaScript files only in the directory specified, without recursion. Directives are processed top to bottom, but the order in which files are included by `require_tree` is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other in the concatenated file, require the prerequisite file first in the manifest. Note that the family of `require` directives prevents files from being included twice in the output. @@ -665,7 +661,7 @@ This can be changed to something else: config.assets.prefix = "/some_other_path" ``` -This is a handy option if you are updating an existing project (pre Rails 3.1) that already uses this path or you wish to use this path for a new resource. +This is a handy option if you are updating an older project that didn't use the asset pipeline and that already uses this path or you wish to use this path for a new resource. ### X-Sendfile Headers diff --git a/guides/source/configuring.md b/guides/source/configuring.md index eae0f5b641..446f767f0c 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -135,8 +135,6 @@ These configuration methods are to be called on a `Rails::Railtie` object, such ### Configuring Assets -Rails 3.1 and up, by default, is set up to use the `sprockets` gem to manage assets within an application. This gem concatenates and compresses assets in order to make serving them much less painful. - * `config.assets.enabled` a flag that controls whether the asset pipeline is enabled. It is explicitly initialized in `config/application.rb`. * `config.assets.compress` a flag that enables the compression of compiled assets. It is explicitly set to true in `config/production.rb`. @@ -165,7 +163,7 @@ Rails 3.1 and up, by default, is set up to use the `sprockets` gem to manage ass ### Configuring Generators -Rails 3 allows you to alter what generators are used with the `config.generators` method. This method takes a block: +Rails allows you to alter what generators are used with the `config.generators` method. This method takes a block: ```ruby config.generators do |g| diff --git a/guides/source/engines.md b/guides/source/engines.md index f1e2780eae..116a7e67cd 100644 --- a/guides/source/engines.md +++ b/guides/source/engines.md @@ -35,7 +35,7 @@ Finally, engines would not have been possible without the work of James Adam, Pi Generating an engine -------------------- -To generate an engine with Rails 3.2, you will need to run the plugin generator and pass it options as appropriate to the need. For the "blorgh" example, you will need to create a "mountable" engine, running this command in a terminal: +To generate an engine, you will need to run the plugin generator and pass it options as appropriate to the need. For the "blorgh" example, you will need to create a "mountable" engine, running this command in a terminal: ```bash $ rails plugin new blorgh --mountable diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index d22b2f8ef6..ee563e72d5 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -594,8 +594,6 @@ The following two forms both upload a file. <% end %> ``` -NOTE: Since Rails 3.1, forms rendered using `form_for` have their encoding set to `multipart/form-data` automatically once a `file_field` is used inside the block. Previous versions required you to set this explicitly. - Rails provides the usual pair of helpers: the barebones `file_field_tag` and the model oriented `file_field`. The only difference with other helpers is that you cannot set a default value for file inputs as this would have no meaning. As you would expect in the first case the uploaded file is in `params[:picture]` and in the second case in `params[:person][:picture]`. ### What Gets Uploaded diff --git a/guides/source/generators.md b/guides/source/generators.md index d23110edd6..62de5a70bb 100644 --- a/guides/source/generators.md +++ b/guides/source/generators.md @@ -15,8 +15,6 @@ After reading this guide, you will know: -------------------------------------------------------------------------------- -NOTE: This guide is about generators in Rails 3, previous versions are not covered. - First Contact ------------- diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index b23ae04380..dbaa3ec576 100644 --- a/guides/source/layouts_and_rendering.md +++ b/guides/source/layouts_and_rendering.md @@ -160,21 +160,6 @@ def update end ``` -To be explicit, you can use `render` with the `:action` option (though this is no longer necessary in Rails 3.0): - -```ruby -def update - @book = Book.find(params[:id]) - if @book.update_attributes(params[:book]) - redirect_to(@book) - else - render action: "edit" - end -end -``` - -WARNING: Using `render` with `:action` is a frequent source of confusion for Rails newcomers. The specified action is used to determine which view to render, but Rails does _not_ run any of the code for that action in the controller. Any instance variables that you require in the view must be set up in the current action before calling `render`. - #### Rendering an Action's Template from Another Controller What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with `render`, which accepts the full path (relative to `app/views`) of the template to render. For example, if you're running code in an `AdminProductsController` that lives in `app/controllers/admin`, you can render the results of an action to a template in `app/views/products` this way: @@ -674,7 +659,7 @@ There are three tag options available for the `auto_discovery_link_tag`: The `javascript_include_tag` helper returns an HTML `script` tag for each source provided. -If you are using Rails with the [Asset Pipeline](asset_pipeline.html) enabled, this helper will generate a link to `/assets/javascripts/` rather than `public/javascripts` which was used in earlier versions of Rails. This link is then served by the Sprockets gem, which was introduced in Rails 3.1. +If you are using Rails with the [Asset Pipeline](asset_pipeline.html) enabled, this helper will generate a link to `/assets/javascripts/` rather than `public/javascripts` which was used in earlier versions of Rails. This link is then served by the asset pipeline. A JavaScript file within a Rails application or Rails engine goes in one of three locations: `app/assets`, `lib/assets` or `vendor/assets`. These locations are explained in detail in the [Asset Organization section in the Asset Pipeline Guide](asset_pipeline.html#asset-organization) @@ -843,7 +828,7 @@ You can even use dynamic paths such as `cache/#{current_site}/main/display`. The `image_tag` helper builds an HTML `` tag to the specified file. By default, files are loaded from `public/images`. -WARNING: Note that you must specify the extension of the image. Previous versions of Rails would allow you to just use the image name and would append `.png` if no extension was given but Rails 3.0 does not. +WARNING: Note that you must specify the extension of the image. ```erb <%= image_tag "header.png" %> @@ -1091,8 +1076,6 @@ Every partial also has a local variable with the same name as the partial (minus Within the `customer` partial, the `customer` variable will refer to `@new_customer` from the parent view. -WARNING: In previous versions of Rails, the default local variable would look for an instance variable with the same name as the partial in the parent. This behavior was deprecated in 2.3 and has been removed in Rails 3.0. - If you have an instance of a model to render into a partial, you can use a shorthand syntax: ```erb @@ -1120,7 +1103,7 @@ Partials are very useful in rendering collections. When you pass a collection to When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within the `_product` partial, you can refer to `product` to get the instance that is being rendered. -In Rails 3.0, there is also a shorthand for this. Assuming `@products` is a collection of `product` instances, you can simply write this in the `index.html.erb` to produce the same result: +There is also a shorthand for this. Assuming `@products` is a collection of `product` instances, you can simply write this in the `index.html.erb` to produce the same result: ```html+erb

Products

diff --git a/guides/source/plugins.md b/guides/source/plugins.md index 42746e34d7..f8f04c3c67 100644 --- a/guides/source/plugins.md +++ b/guides/source/plugins.md @@ -27,16 +27,13 @@ goodness. Setup ----- -_"vendored plugins"_ were available in previous versions of Rails, but they are deprecated in -Rails 3.2, and will not be available in the future. - Currently, Rails plugins are built as gems, _gemified plugins_. They can be shared across different rails applications using RubyGems and Bundler if desired. ### Generate a gemified plugin. -Rails 3.1 ships with a `rails plugin new` command which creates a +Rails ships with a `rails plugin new` command which creates a skeleton for developing any kind of Rails extension with the ability to run integration tests using a dummy Rails application. See usage and options by asking for help: diff --git a/guides/source/routing.md b/guides/source/routing.md index 0e78e7d4cd..241a7cfec6 100644 --- a/guides/source/routing.md +++ b/guides/source/routing.md @@ -733,12 +733,6 @@ get '*a/foo/*b', to: 'test#index' would match `zoo/woo/foo/bar/baz` with `params[:a]` equals `'zoo/woo'`, and `params[:b]` equals `'bar/baz'`. -NOTE: Starting from Rails 3.1, wildcard segments will always match the optional format segment by default. For example if you have this route: - -```ruby -get '*pages', to: 'pages#show' -``` - NOTE: By requesting `'/foo/bar.json'`, your `params[:pages]` will be equals to `'foo/bar'` with the request format of JSON. If you want the old 3.0.x behavior back, you could supply `format: false` like this: ```ruby From 350b122ecc86584cdee6aa39ed2772f9d49e68d2 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 7 Dec 2012 23:22:51 -0800 Subject: [PATCH 17/21] Remove reference to background queue in mailer guide. Mailers are always async now, and we already discuss queueing lower down in the guide. --- guides/source/action_mailer_basics.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 9411ac7325..b2ccc2d82c 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -149,8 +149,6 @@ This provides a much simpler implementation that does not require the registerin The method `welcome_email` returns a `Mail::Message` object which can then just be told `deliver` to send itself out. -WARNING: Sending out an email should only take a fraction of a second. If you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job. - ### Auto encoding header values Action Mailer now handles the auto encoding of multibyte characters inside of headers and bodies. From 1ef8138f9edc23e4146d4d78138e700321586e0b Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 7 Dec 2012 23:26:13 -0800 Subject: [PATCH 18/21] Fill out Active Support Core Extensions 'you will learn' list. --- guides/source/active_support_core_extensions.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/guides/source/active_support_core_extensions.md b/guides/source/active_support_core_extensions.md index 666e9ee201..1d79ee2565 100644 --- a/guides/source/active_support_core_extensions.md +++ b/guides/source/active_support_core_extensions.md @@ -7,6 +7,11 @@ It offers a richer bottom-line at the language level, targeted both at the devel After reading this guide, you will know: +* What Core Extensions are. +* How to load all extensions. +* How to cherry-pick just the extensions you want. +* What extensions ActiveSupport provides. + -------------------------------------------------------------------------------- How to Load Core Extensions From aa1b9037bf609d11ed0a2a4d5f2028c66ffc2351 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 7 Dec 2012 23:31:17 -0800 Subject: [PATCH 19/21] Fill out API Documentation Guidelines 'you will learn' list. --- guides/source/api_documentation_guidelines.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 0126fc94d1..5c4aae8900 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -5,6 +5,10 @@ This guide documents the Ruby on Rails API documentation guidelines. After reading this guide, you will know: +* What RDoc is. +* How to write effective prose for documentation purposes. +* Style guidlines for documenting different kinds of Ruby code. + -------------------------------------------------------------------------------- RDoc From 4085dd60108a95da22854ee4ecb683578a9a3e7d Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 8 Dec 2012 23:02:18 +0530 Subject: [PATCH 20/21] Revert "Introduce Bundler and Gemfiles in a NOTE" This reverts commit 83cb6fbd13f3c5ea3106b9a57964b1a6fb243682. Reason: very trivial [ci skip] --- guides/source/getting_started.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 37760e4393..54200768e6 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -115,8 +115,6 @@ $ rails new blog This will create a Rails application called Blog in a directory called blog and install the gem dependencies that are already mentioned in `Gemfile` using `bundle install`. -NOTE: A Gemfile is a file that contains the list of all the gems that you require to run your application - the so called dependencies. With it, a program called Bundler can make sure that your machine has all of the requirements installed. This is the de facto way in Ruby to make sure that a machine is set up correctly to run a given program and Rails takes advantage of it to install some commonly-used gems. For more information, visit [Bundler's homepage](http://gembundler.com/). - TIP: You can see all of the command line options that the Rails application builder accepts by running `rails new -h`. From 729798068a54dbbe553c71f0283cb6ad74c2e77c Mon Sep 17 00:00:00 2001 From: Vijay Dev Date: Sat, 8 Dec 2012 23:10:38 +0530 Subject: [PATCH 21/21] copy edits [ci skip] --- guides/source/api_documentation_guidelines.md | 3 +-- guides/source/ruby_on_rails_guides_guidelines.md | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index 5c4aae8900..d0499878da 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -5,9 +5,8 @@ This guide documents the Ruby on Rails API documentation guidelines. After reading this guide, you will know: -* What RDoc is. * How to write effective prose for documentation purposes. -* Style guidlines for documenting different kinds of Ruby code. +* Style guidelines for documenting different kinds of Ruby code. -------------------------------------------------------------------------------- diff --git a/guides/source/ruby_on_rails_guides_guidelines.md b/guides/source/ruby_on_rails_guides_guidelines.md index 5031a1b531..a78711f4b2 100644 --- a/guides/source/ruby_on_rails_guides_guidelines.md +++ b/guides/source/ruby_on_rails_guides_guidelines.md @@ -5,8 +5,8 @@ This guide documents guidelines for writing Ruby on Rails Guides. This guide fol After reading this guide, you will know: -* Standards for writing and formatting rails guide source files -* How to generate HTML documentation from source files +* About the conventions to be used in Rails documentation. +* How to generate guides locally. --------------------------------------------------------------------------------