diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/4_1_release_notes.md | 206 | ||||
| -rw-r--r-- | guides/source/_welcome.html.erb | 4 | ||||
| -rw-r--r-- | guides/source/plugins.md | 30 | ||||
| -rw-r--r-- | guides/source/rails_on_rack.md | 2 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 70 |
5 files changed, 246 insertions, 66 deletions
diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md index 0e3e2037ff..5c50ed83ea 100644 --- a/guides/source/4_1_release_notes.md +++ b/guides/source/4_1_release_notes.md @@ -4,6 +4,7 @@ Ruby on Rails 4.1 Release Notes Highlights in Rails 4.1: * Variants +* Spring * Action View extracted from Action Pack These release notes cover only the major changes. To know about various bug @@ -28,38 +29,111 @@ guide. Major Features -------------- -* Variants +### Variants + +We often want to render different html/json/xml templates for phones, +tablets, and desktop browsers. Variants makes it easy. + +The request variant is a specialization of the request format, like `:tablet`, +`:phone`, or `:desktop`. + +You can set the variant in a before_action: + +```ruby +request.variant = :tablet if request.user_agent =~ /iPad/ +``` + +Respond to variants in the action just like you respond to formats: + +```ruby +respond_to do |format| + format.html do |html| + html.tablet # renders app/views/projects/show.html+tablet.erb + html.phone { extra_setup; render ... } + end +end +``` + +Provide separate templates for each format and variant: + +``` +app/views/projects/show.html.erb +app/views/projects/show.html+tablet.erb +app/views/projects/show.html+phone.erb +``` + +### Spring + +New Rails 4.1 applications will ship with "springified" binstubs. This means +that `bin/rails` and `bin/rake` will automatically take advantage preloaded +spring environments. + +**running rake tasks:** + +``` +bin/rake routes +``` + +**running tests:** + +``` +bin/rake test +bin/rake test test/models +bin/rake test test/models/user_test.rb +``` + +**running a console:** + +``` +bin/rails console +``` + +**spring introspection:** + +``` +$ bundle exec spring status +Spring is running: - We often want to render different html/json/xml templates for phones, - tablets, and desktop browsers. Variants make it easy. + 1182 spring server | my_app | started 29 mins ago + 3656 spring app | my_app | started 23 secs ago | test mode + 3746 spring app | my_app | started 10 secs ago | development mode +``` - The request variant is a specialization of the request format, like :tablet, - :phone, or :desktop. +Have a look at the +[Spring README](https://github.com/jonleighton/spring/blob/master/README.md) to +see a all available features. - You can set the variant in a before_action: +### Active Record enums - ```ruby - request.variant = :tablet if request.user_agent =~ /iPad/ - ``` +Declare an enum attribute where the values map to integers in the database, but +can be queried by name. - Respond to variants in the action just like you respond to formats: +```ruby +class Conversation < ActiveRecord::Base + enum status: [ :active, :archived ] +end - ```ruby - respond_to do |format| - format.html do |html| - html.tablet # renders app/views/projects/show.html+tablet.erb - html.phone { extra_setup; render ... } - end - end - ``` +conversation.archive! +conversation.active? # => false +conversation.status # => "archived" - Provide separate templates for each format and variant: +Conversation.archived # => Relation for all archived Conversations +``` - ``` - app/views/projects/show.html.erb - app/views/projects/show.html+tablet.erb - app/views/projects/show.html+phone.erb - ``` +See +[active_record/enum.rb](https://github.com/rails/rails/blob/4-1-stable/activerecord/lib/active_record/enum.rb#L2-L42) +for a detailed write up. + +### Application message verifier. + +Create a message verifier that can be used to generate and verify signed +messages in the application. + +```ruby +message = Rails.application.message_verifier('salt').generate('my sensible data') +Rails.application.message_verifier('salt').verify(message) +# => 'my sensible data' +``` Documentation ------------- @@ -81,20 +155,29 @@ for detailed changes. * Removed deprecated `threadsafe!` from Rails Config. * Removed deprecated `ActiveRecord::Generators::ActiveModel#update_attributes` in - favor of `ActiveRecord::Generators::ActiveModel#update` + favor of `ActiveRecord::Generators::ActiveModel#update`. -* Removed deprecated `config.whiny_nils` option +* Removed deprecated `config.whiny_nils` option. * Removed deprecated rake tasks for running tests: `rake test:uncommitted` and `rake test:recent`. ### Notable changes +* The [Spring application + preloader](https://github.com/jonleighton/spring) is now installed + by default for new applications. It uses the development group of + the Gemfile, so will not be installed in + production. ([Pull Request](https://github.com/rails/rails/pull/12958)) + * `BACKTRACE` environment variable to show unfiltered backtraces for test failures. ([Commit](https://github.com/rails/rails/commit/84eac5dab8b0fe9ee20b51250e52ad7bfea36553)) -* Exposed `MiddlewareStack#unshift` to environment configuration. ([Pull Request](https://github.com/rails/rails/pull/12479)) +* Exposed `MiddlewareStack#unshift` to environment + configuration. ([Pull Request](https://github.com/rails/rails/pull/12479)) +* Add `Application#message_verifier` method to return a message + verifier. ([Pull Request](https://github.com/rails/rails/pull/12995)) Action Mailer ------------- @@ -137,6 +220,17 @@ for detailed changes. ### Removals +* Removed `MultiJSON` dependency. As a result, `ActiveSupport::JSON.decode` + no longer accepts an options hash for `MultiJSON`. ([Pull Request](https://github.com/rails/rails/pull/10576) / [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + +* Removed support for the `encode_json` hook used for encoding custom objects into + JSON. This feature has been extracted into the [activesupport-json_encoder](https://github.com/rails/activesupport-json_encoder) + gem. + ([Related Pull Request](https://github.com/rails/rails/pull/12183) / + [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + +* Removed deprecated `ActiveSupport::JSON::Variable` with no replacement. + * Removed deprecated `String#encoding_aware?` core extensions (`core_ext/string/encoding`). * Removed deprecated `Module#local_constant_names` in favor of `Module#local_constants`. @@ -171,8 +265,32 @@ for detailed changes. explicitly convert the value into an AS::Duration, i.e. `5.ago` => `5.seconds.ago` ([Pull Request](https://github.com/rails/rails/pull/12389)) +* Deprecated the require path `active_support/core_ext/object/to_json`. Require + `active_support/core_ext/object/json` instead. ([Pull Request](https://github.com/rails/rails/pull/12203)) + +* Deprecated `ActiveSupport::JSON::Encoding::CircularReferenceError`. This feature + has been extracted into the [activesupport-json_encoder](https://github.com/rails/activesupport-json_encoder) + gem. + ([Pull Request](https://github.com/rails/rails/pull/12785) / + [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + +* Deprecated `ActiveSupport.encode_big_decimal_as_string` option. This feature has + been extracetd into the [activesupport-json_encoder](https://github.com/rails/activesupport-json_encoder) + gem. + ([Pull Request](https://github.com/rails/rails/pull/13060) / + [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + ### Notable changes +* `ActiveSupport`'s JSON encoder has been rewritten to take advantage of the + JSON gem rather than doing custom encoding in pure-Ruby. + ([Pull Request](https://github.com/rails/rails/pull/12183) / + [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + +* Improved compatibility with the JSON gem. + ([Pull Request](https://github.com/rails/rails/pull/12862) / + [More Details](upgrading_ruby_on_rails.html#changes-in-json-handling)) + * Added `ActiveSupport::Testing::TimeHelpers#travel` and `#travel_to`. These methods change current time to the given time or time difference by stubbing `Time.now` and @@ -207,6 +325,9 @@ for detailed changes. * Removed deprecated `page_cache_extension` config. +* Removed deprecated `ActionController::RecordIdentifier`, use + `ActionView::RecordIdentifier` instead. + * Removed deprecated constants from Action Controller: ActionController::AbstractRequest => ActionDispatch::Request @@ -219,8 +340,8 @@ for detailed changes. ### Notable changes -* Take a hash with options inside array in - `#url_for`. ([Pull Request](https://github.com/rails/rails/pull/9599)) +* `#url_for` takes a hash with options inside an + array. ([Pull Request](https://github.com/rails/rails/pull/9599)) * Added `session#fetch` method fetch behaves similarly to [Hash#fetch](http://www.ruby-doc.org/core-1.9.3/Hash.html#method-i-fetch), @@ -266,29 +387,18 @@ for detailed changes. * Removed deprecated `SchemaStatements#distinct`. -* Moved deprecated `ActiveRecord::TestCase` into the rails test +* Moved deprecated `ActiveRecord::TestCase` into the Rails test suite. The class is no longer public and is only used for internal Rails tests. * Removed support for deprecated option `:restrict` for `:dependent` in associations. -* Removed support for deprecated `delete_sql` in associations. - -* Removed support for deprecated `insert_sql` in associations. - -* Removed support for deprecated `finder_sql` in associations. - -* Removed support for deprecated `counter_sql` in associations. +* Removed support for deprecated `:delete_sql`, `:insert_sql`, `:finder_sql` + and `:counter_sql` options in associations. * Removed deprecated method `type_cast_code` from Column. -* Removed deprecated options `delete_sql` and `insert_sql` from HABTM - association. - -* Removed deprecated options `finder_sql` and `counter_sql` from - collection association. - * Removed deprecated `ActiveRecord::Base#connection` method. Make sure to access it via the class. @@ -299,17 +409,17 @@ for detailed changes. * Removed deprecated methods `partial_updates`, `partial_updates?` and `partial_updates=`. -* Removed deprecated method `scoped` +* Removed deprecated method `scoped`. -* Removed deprecated method `default_scopes?` +* Removed deprecated method `default_scopes?`. * Remove implicit join references that were deprecated in 4.0. -* Removed `activerecord-deprecated_finders` as a dependency +* Removed `activerecord-deprecated_finders` as a dependency. -* Usage of `implicit_readonly` is being removed. Please use `readonly` method +* Removed usage of `implicit_readonly`. Please use `readonly` method explicitly to mark records as - `readonly. ([Pull Request](https://github.com/rails/rails/pull/10769)) + `readonly`. ([Pull Request](https://github.com/rails/rails/pull/10769)) ### Deprecations diff --git a/guides/source/_welcome.html.erb b/guides/source/_welcome.html.erb index 93c177905c..ed2025a75d 100644 --- a/guides/source/_welcome.html.erb +++ b/guides/source/_welcome.html.erb @@ -15,8 +15,8 @@ </p> <% end %> <p> - The guides for Rails 3.2.x are available at <a href="http://guides.rubyonrails.org/v3.2.15/">http://guides.rubyonrails.org/v3.2.15/</a>. + The guides for Rails 3.2.x are available at <a href="http://guides.rubyonrails.org/v3.2.16/">http://guides.rubyonrails.org/v3.2.16/</a>. </p> <p> - The guides for Rails 2.3.x are available at <a href="http://guides.rubyonrails.org/v2.3.11/">http://guides.rubyonrails.org/v2.3.11/</a>. + The guides for Rails 2.3.x are available at <a href="http://guides.rubyonrails.org/v2.3.18/">http://guides.rubyonrails.org/v2.3.18/</a>. </p> diff --git a/guides/source/plugins.md b/guides/source/plugins.md index d0aa2e55a2..8587bd48b2 100644 --- a/guides/source/plugins.md +++ b/guides/source/plugins.md @@ -3,9 +3,9 @@ The Basics of Creating Rails Plugins A Rails plugin is either an extension or a modification of the core framework. Plugins provide: -* a way for developers to share bleeding-edge ideas without hurting the stable code base -* a segmented architecture so that units of code can be fixed or updated on their own release schedule -* an outlet for the core developers so that they don't have to include every cool new feature under the sun +* A way for developers to share bleeding-edge ideas without hurting the stable code base. +* A segmented architecture so that units of code can be fixed or updated on their own release schedule. +* An outlet for the core developers so that they don't have to include every cool new feature under the sun. After reading this guide, you will know: @@ -48,7 +48,7 @@ See usage and options by asking for help: $ rails plugin --help ``` -Testing your newly generated plugin +Testing Your Newly Generated Plugin ----------------------------------- You can navigate to the directory that contains the plugin, run the `bundle install` command @@ -92,7 +92,7 @@ Run `rake` to run the test. This test should fail because we haven't implemented Great - now you are ready to start development. -Then in `lib/yaffle.rb` add `require "yaffle/core_ext"`: +In `lib/yaffle.rb`, add `require "yaffle/core_ext"`: ```ruby # yaffle/lib/yaffle.rb @@ -219,7 +219,7 @@ $ rails generate model Wickwall last_squawk:string last_tweet:string ``` Now you can create the necessary database tables in your testing database by navigating to your dummy app -and migrating the database. First +and migrating the database. First, run: ```bash $ cd test/dummy @@ -245,7 +245,7 @@ end ``` -We will also add code to define the acts_as_yaffle method. +We will also add code to define the `acts_as_yaffle` method. ```ruby # yaffle/lib/yaffle/acts_as_yaffle.rb @@ -286,7 +286,7 @@ You can then return to the root directory (`cd ../..`) of your plugin and rerun ``` -Getting closer... Now we will implement the code of the acts_as_yaffle method to make the tests pass. +Getting closer... Now we will implement the code of the `acts_as_yaffle` method to make the tests pass. ```ruby # yaffle/lib/yaffle/acts_as_yaffle.rb @@ -310,7 +310,7 @@ end ActiveRecord::Base.send :include, Yaffle::ActsAsYaffle ``` -When you run `rake` you should see the tests all pass: +When you run `rake`, you should see the tests all pass: ```bash 5 tests, 5 assertions, 0 failures, 0 errors, 0 skips @@ -390,7 +390,11 @@ Run `rake` one final time and you should see: 7 tests, 7 assertions, 0 failures, 0 errors, 0 skips ``` -NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use `send("#{self.class.yaffle_text_field}=", string.to_squawk)`. +NOTE: The use of `write_attribute` to write to the field in model is just one example of how a plugin can interact with the model, and will not always be the right method to use. For example, you could also use: + +```ruby +send("#{self.class.yaffle_text_field}=", string.to_squawk) +``` Generators ---------- @@ -398,7 +402,7 @@ Generators Generators can be included in your gem simply by creating them in a lib/generators directory of your plugin. More information about the creation of generators can be found in the [Generators Guide](generators.html) -Publishing your Gem +Publishing Your Gem ------------------- Gem plugins currently in development can easily be shared from any Git repository. To share the Yaffle gem with others, simply @@ -411,12 +415,12 @@ gem 'yaffle', git: 'git://github.com/yaffle_watcher/yaffle.git' After running `bundle install`, your gem functionality will be available to the application. When the gem is ready to be shared as a formal release, it can be published to [RubyGems](http://www.rubygems.org). -For more information about publishing gems to RubyGems, see: [Creating and Publishing Your First Ruby Gem](http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html) +For more information about publishing gems to RubyGems, see: [Creating and Publishing Your First Ruby Gem](http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html). RDoc Documentation ------------------ -Once your plugin is stable and you are ready to deploy do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy. +Once your plugin is stable and you are ready to deploy, do everyone else a favor and document it! Luckily, writing documentation for your plugin is easy. The first step is to update the README file with detailed information about how to use your plugin. A few key things to include are: diff --git a/guides/source/rails_on_rack.md b/guides/source/rails_on_rack.md index b42c8fb81b..9c92cf3aea 100644 --- a/guides/source/rails_on_rack.md +++ b/guides/source/rails_on_rack.md @@ -144,7 +144,7 @@ use Rack::ETag run MyApp::Application.routes ``` -Purpose of each of this middlewares is explained in the [Internal Middlewares](#internal-middleware-stack) section. +The default middlewares shown here (and some others) are each summarized in the [Internal Middlewares](#internal-middleware-stack) section, below. ### Configuring Middleware Stack diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index 3fbc913d8b..596682bb1f 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -27,6 +27,72 @@ Upgrading from Rails 4.0 to Rails 4.1 NOTE: This section is a work in progress. +### Spring + +If you want to use Spring as your application preloader you need to: + +1. add `gem 'spring', group: :development` to your `Gemfile`. +2. install spring using `bundle install`. +3. springify your binstubs with `bundle exec spring binstub --all`. + +NOTE: User defined rake tasks will run in the `development` environment by +default. If you want them to run in other environments consult the +[Spring README](https://github.com/jonleighton/spring#rake). + +### Changes in JSON handling + +The are a few major changes related to JSON handling in Rails 4.1. + +#### MultiJSON removal + +MultiJSON has reached its [end-of-life](https://github.com/rails/rails/pull/10576) +and has been removed from Rails. + +If your application currently depend on MultiJSON directly, you have a few options: + +1. Add 'multi_json' to your Gemfile. Note that this might cease to work in the future + +2. Migrate away from MultiJSON by using `obj.to_json`, and `JSON.parse(str)` instead. + +WARNING: Do not simply replace `MultiJson.dump` and `MultiJson.load` with +`JSON.dump` and `JSON.load`. These JSON gem APIs are meant for serializing and +deserializing arbitrary Ruby objects and are generally [unsafe](http://www.ruby-doc.org/stdlib-2.0.0/libdoc/json/rdoc/JSON.html#method-i-load). + +#### JSON gem compatibility + +Historically, Rails had some compatibility issues with the JSON gem. Using +`JSON.generate` and `JSON.dump` inside a Rails application could produce +unexpected errors. + +Rails 4.1 fixed these issues by isolating its own encoder from the JSON gem. The +JSON gem APIs will function as normal, but they will not have access to any +Rails-specific features. For example: + +```ruby +class FooBar + def as_json(options = nil) + { foo: "bar" } + end +end + +>> FooBar.new.to_json # => "{\"foo\":\"bar\"}" +>> JSON.generate(FooBar.new, quirks_mode: true) # => "\"#<FooBar:0x007fa80a481610>\"" +``` + +#### New JSON encoder + +The JSON encoder in Rails 4.1 has been rewritten to take advantage of the JSON +gem. For most applications, this should be a transparent change. However, as +part of the rewrite, the following features have been removed from the encoder: + +1. Circular data structure detection +2. Support for the `encode_json` hook +3. Option to encode `BigDecimal` objects as numbers instead of strings + +If you application depends on one of these features, you can get them back by +adding the [`activesupport-json_encoder`](https://github.com/rails/activesupport-json_encoder) +gem to your Gemfile. + ### Methods defined in Active Record fixtures Rails 4.1 evaluates each fixture's ERB in a separate context, so helper methods @@ -367,7 +433,7 @@ Upgrading from Rails 3.1 to Rails 3.2 If your application is currently on any version of Rails older than 3.1.x, you should upgrade to Rails 3.1 before attempting an update to Rails 3.2. -The following changes are meant for upgrading your application to Rails 3.2.15, +The following changes are meant for upgrading your application to Rails 3.2.16, the last 3.2.x version of Rails. ### Gemfile @@ -375,7 +441,7 @@ the last 3.2.x version of Rails. Make the following changes to your `Gemfile`. ```ruby -gem 'rails', '3.2.15' +gem 'rails', '3.2.16' group :assets do gem 'sass-rails', '~> 3.2.6' |