diff --git a/guides/source/3_1_release_notes.md b/guides/source/3_1_release_notes.md index 3d64c16d6a269..a020458d2f0c8 100644 --- a/guides/source/3_1_release_notes.md +++ b/guides/source/3_1_release_notes.md @@ -20,7 +20,7 @@ repository on GitHub. Upgrading to Rails 3.1 ---------------------- -If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3 in case you haven't and make sure your application still runs as expected before attempting to update to Rails 3.1. Then take heed of the following changes: +If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3 in case you haven't and make sure your application still runs as expected before attempting to update to Rails 3.1. A list of things to watch out for when upgrading is available in the [Upgrading from Rails 3.0 to Rails 3.1](upgrading_from_rails_3.0_to_3.1.html) guide. ### Rails 3.1 requires at least Ruby 1.8.7 diff --git a/guides/source/3_2_release_notes.md b/guides/source/3_2_release_notes.md index fc4fb1101f3e7..03957f7b10c8e 100644 --- a/guides/source/3_2_release_notes.md +++ b/guides/source/3_2_release_notes.md @@ -20,7 +20,7 @@ repository on GitHub. Upgrading to Rails 3.2 ---------------------- -If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3.1 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 3.2. Then take heed of the following changes: +If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3.1 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 3.2. A list of things to watch out for when upgrading is available in the [Upgrading from Rails 3.1 to Rails 3.2](upgrading_from_rails_3.1_to_3.2.html) guide. ### Rails 3.2 requires at least Ruby 1.8.7 diff --git a/guides/source/4_0_release_notes.md b/guides/source/4_0_release_notes.md index 7249c3fb56920..2f6cad9999528 100644 --- a/guides/source/4_0_release_notes.md +++ b/guides/source/4_0_release_notes.md @@ -20,7 +20,7 @@ repository on GitHub. Upgrading to Rails 4.0 ---------------------- -If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3.2 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 4.0. A list of things to watch out for when upgrading is available in the [Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-3-2-to-rails-4-0) guide. +If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3.2 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 4.0. A list of things to watch out for when upgrading is available in the [Upgrading from Rails 3.2 to Rails 4.0](upgrading_from_rails_3.2_to_4.0.html) guide. Creating a Rails 4.0 application diff --git a/guides/source/4_1_release_notes.md b/guides/source/4_1_release_notes.md index 50caddc081a77..e81e6251e8b19 100644 --- a/guides/source/4_1_release_notes.md +++ b/guides/source/4_1_release_notes.md @@ -25,7 +25,7 @@ coverage before going in. You should also first upgrade to Rails 4.0 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 4.1. A list of things to watch out for when upgrading is available in the -[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-0-to-rails-4-1) +[Upgrading from Rails 4.0 to Rails 4.1](upgrading_from_rails_4.0_to_4.1.html) guide. diff --git a/guides/source/4_2_release_notes.md b/guides/source/4_2_release_notes.md index 3926a9481e157..9c6e4bb5ac9ae 100644 --- a/guides/source/4_2_release_notes.md +++ b/guides/source/4_2_release_notes.md @@ -25,8 +25,7 @@ If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 4.1 in case you haven't and make sure your application still runs as expected before attempting to upgrade to Rails 4.2. A list of things to watch out for when upgrading is -available in the guide [Upgrading Ruby on -Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-1-to-rails-4-2). +available in the [Upgrading from Rails 4.1 to Rails 4.2](upgrading_from_rails_4.1_to_4.2.html) guide. Major Features diff --git a/guides/source/5_0_release_notes.md b/guides/source/5_0_release_notes.md index 6f1048d08a0b4..8bd6b41d19336 100644 --- a/guides/source/5_0_release_notes.md +++ b/guides/source/5_0_release_notes.md @@ -29,7 +29,7 @@ coverage before going in. You should also first upgrade to Rails 4.2 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 5.0. A list of things to watch out for when upgrading is available in the -[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-4-2-to-rails-5-0) +[Upgrading from Rails 4.2 to Rails 5.0](upgrading_from_rails_4.2_to_5.0.html) guide. diff --git a/guides/source/5_1_release_notes.md b/guides/source/5_1_release_notes.md index 8d374b37bc1bb..eac27792ac18d 100644 --- a/guides/source/5_1_release_notes.md +++ b/guides/source/5_1_release_notes.md @@ -29,7 +29,7 @@ coverage before going in. You should also first upgrade to Rails 5.0 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 5.1. A list of things to watch out for when upgrading is available in the -[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-5-0-to-rails-5-1) +[Upgrading from Rails 5.0 to Rails 5.1](upgrading_from_rails_5.0_to_5.1.html) guide. diff --git a/guides/source/5_2_release_notes.md b/guides/source/5_2_release_notes.md index fc9927e69653b..260c8cb646386 100644 --- a/guides/source/5_2_release_notes.md +++ b/guides/source/5_2_release_notes.md @@ -26,7 +26,7 @@ coverage before going in. You should also first upgrade to Rails 5.1 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 5.2. A list of things to watch out for when upgrading is available in the -[Upgrading Ruby on Rails](upgrading_ruby_on_rails.html#upgrading-from-rails-5-1-to-rails-5-2) +[Upgrading from Rails 5.1 to Rails 5.2](upgrading_from_rails_5.1_to_5.2.html) guide. Major Features diff --git a/guides/source/documents.yaml b/guides/source/documents.yaml index ae5a1d3df120a..0af0c3367e44a 100644 --- a/guides/source/documents.yaml +++ b/guides/source/documents.yaml @@ -1,63 +1,52 @@ -- - name: Start Here +- name: Start Here documents: - - - name: Getting Started with Rails + - name: Getting Started with Rails url: getting_started.html description: Everything you need to know to install Rails and create your first application. - - - name: Install Ruby on Rails + - name: Install Ruby on Rails url: install_ruby_on_rails.html description: Learn how to install the Ruby programming language and Ruby on Rails. -- - name: Models +- name: Models documents: - - - name: Active Record Basics + - name: Active Record Basics url: active_record_basics.html description: > Active Record allows your models to interact with the application's database. This guide will get you started with Active Record models and persistence to the database. - - - name: Active Record Migrations + - name: Active Record Migrations url: active_record_migrations.html description: > Migrations are a feature of Active Record that allows you to evolve your database schema over time. Rather than write schema modifications in pure SQL, migrations allow you to use a Ruby DSL to describe changes to your tables. - - - name: Active Record Validations + - name: Active Record Validations url: active_record_validations.html description: > Validations are used to ensure that only valid data is saved into your database. This guide teaches you how to validate the state of objects before they go into the database, using Active Record's validations feature. - - - name: Active Record Callbacks + - name: Active Record Callbacks url: active_record_callbacks.html description: > Callbacks make it possible to write code that will run whenever an object is created, updated, destroyed, etc. This guide teaches you how to hook into this object life cycle of Active Record objects. - - - name: Active Record Associations + - name: Active Record Associations url: association_basics.html description: > In Active Record, an association is a connection between two Active Record models. This guide covers all the associations provided by Active Record. - - - name: Active Record Query Interface + - name: Active Record Query Interface url: active_record_querying.html description: > Instead of using raw SQL to find database records, Active Record provides better ways to carry out the same operations. This guide covers different ways to retrieve data from the database using Active Record. - - - name: Active Model Basics + - name: Active Model Basics url: active_model_basics.html description: > Active Model allows you to create plain Ruby objects that integrate with @@ -65,98 +54,81 @@ Active Model also helps build custom ORMs for use outside of the Rails framework. This guide provides you with all you need to get started using Active Model classes. -- - name: Views +- name: Views documents: - - - name: Action View Overview + - name: Action View Overview url: action_view_overview.html description: > Action View is responsible for generating the HTML for web responses. This guide provides an introduction to Action View. - - - name: Layouts and Rendering in Rails + - name: Layouts and Rendering in Rails url: layouts_and_rendering.html description: This guide covers the basic layout features of Action Controller and Action View, including rendering and redirecting, using content_for blocks, and working with partials. - - - name: Action View Helpers + - name: Action View Helpers url: action_view_helpers.html description: > Action View has helpers for handling everything from formatting dates and linking to images, to sanitizing and localizing content. This guide introduces a few of the more common Action View helpers. - - - name: Action View Form Helpers + - name: Action View Form Helpers url: form_helpers.html description: > HTML forms can quickly become tedious to write and maintain because of the need to handle form control naming and its numerous attributes. Rails does away with this complexity by providing view helpers for generating form markup. -- - name: Controllers +- name: Controllers documents: - - - name: Action Controller Overview + - name: Action Controller Overview url: action_controller_overview.html description: > Action Controllers are the core of a web request in Rails. This guide covers how controllers work and how they fit into the request cycle of your application. Topics include accessing parameters in controller actions, using sessions and cookies, controller callbacks. - - - name: Action Controller Advanced Topics + - name: Action Controller Advanced Topics url: action_controller_advanced_topics.html description: > This guide covers a number of advanced topics related to controllers in a Rails application such as protecting against cross-site request forgery, HTTP authentication, data streaming, and dealing with exceptions, log filtering, and more. - - - name: Rails Routing from the Outside In + - name: Rails Routing from the Outside In url: routing.html description: > The Rails router recognizes URLs and dispatches them to a controller's action. This guide covers the user-facing features of Rails routing. If you want to understand how to use routing in your own Rails applications, start here. -- - name: Other Components +- name: Other Components documents: - - - name: Active Support Core Extensions + - name: Active Support Core Extensions url: active_support_core_extensions.html description: > Active Support provides Ruby language extensions and utilities. It enriches the Ruby language for the development of Rails applications, and for the development of Ruby on Rails itself. - - - name: Action Mailer Basics + - name: Action Mailer Basics url: action_mailer_basics.html description: > This guide provides you with all you need to get started in sending emails from your application, and many internals of Action Mailer. - - - name: Action Mailbox Basics + - name: Action Mailbox Basics url: action_mailbox_basics.html description: This guide describes how to use Action Mailbox to receive emails. - - - name: Action Text Overview + - name: Action Text Overview url: action_text_overview.html description: This guide describes how to use Action Text to handle rich text content. - - - name: Active Job Basics + - name: Active Job Basics url: active_job_basics.html description: > Active Job is a framework for declaring background jobs and making them run on a variety of queuing backends. This guide provides you with all you need to get started creating, enqueuing, and executing background jobs. - - - name: Active Storage Overview + - name: Active Storage Overview url: active_storage_overview.html description: > Active Storage facilitates uploading files to a cloud storage service, transforming uploads and extracting metadata. This guide covers how to attach files to your Active Record models. - - - name: Action Cable Overview + - name: Action Cable Overview url: action_cable_overview.html description: > Action Cable integrates WebSockets with the rest of your Rails @@ -164,243 +136,188 @@ the same style and form as the rest of your Rails application. This guide explains how Action Cable works, and how to use WebSockets to create real-time features. -- - name: Digging Deeper +- name: Digging Deeper documents: - - - name: Rails Internationalization (I18n) API + - name: Rails Internationalization (I18n) API url: i18n.html description: This guide covers how to add internationalization to your applications. Your application will be able to translate content to different languages, change pluralization rules, use correct date formats for each country, and so on. - - - name: Testing Rails Applications + - name: Testing Rails Applications url: testing.html description: This guide explores how to write tests in Rails. It also covers test configuration and compares approaches to testing an application. - - - name: Debugging Rails Applications + - name: Debugging Rails Applications url: debugging_rails_applications.html description: This guide describes how to debug Rails applications. It covers the different ways of achieving this and how to understand what is happening "behind the scenes" of your code. - - - name: Configuring Rails Applications + - name: Configuring Rails Applications url: configuring.html description: This guide covers the basic configuration settings for a Rails application. - - - name: The Rails Command Line + - name: The Rails Command Line url: command_line.html description: > There are a few commands that are absolutely critical to your everyday usage of Rails. This guide covers the command line tools provided by Rails. - - - name: The Asset Pipeline + - name: The Asset Pipeline url: asset_pipeline.html description: > The asset pipeline guide explains how to use Propshaft, a framework that handles essential asset management tasks. - - - name: Working with JavaScript in Rails + - name: Working with JavaScript in Rails url: working_with_javascript_in_rails.html description: > This guide explains how to use import maps or jsbundling-rails to include JavaScript in Rails applications, and covers the basics of working with Turbo in Rails. - - - name: The Rails Initialization Process + - name: The Rails Initialization Process work_in_progress: true url: initialization.html description: > This guide explains the internals of the initialization process in Rails. It is an extremely in-depth guide and recommended for advanced Rails developers. - - - name: Autoloading and Reloading + - name: Autoloading and Reloading url: autoloading_and_reloading_constants.html description: This guide documents how autoloading and reloading constants work. - - - name: Active Support Instrumentation + - name: Active Support Instrumentation work_in_progress: true url: active_support_instrumentation.html description: This guide explains how to use the instrumentation API inside of Active Support to measure events inside of Rails and other Ruby code. - - - name: Using Rails for API-only Applications + - name: Using Rails for API-only Applications url: api_app.html description: This guide explains how to effectively use Rails to develop a JSON API application. -- - name: Going to Production +- name: Going to Production documents: - - - name: Tuning Performance for Deployment + - name: Tuning Performance for Deployment url: tuning_performance_for_deployment.html description: This guide covers performance and concurrency configuration for deploying your production Ruby on Rails application. - - - name: "Caching with Rails: An Overview" + - name: "Caching with Rails: An Overview" url: caching_with_rails.html description: This guide is an introduction to speeding up your Rails application with caching. - - - name: Securing Rails Applications + - name: Securing Rails Applications url: security.html description: This guide describes common security problems in web applications and how to avoid them with Rails. - - - name: Error Reporting in Rails Applications + - name: Error Reporting in Rails Applications url: error_reporting.html description: This guide introduces ways to manage errors that occur in Ruby on Rails applications. -- - name: Advanced Active Record +- name: Advanced Active Record documents: - - - name: Active Record and PostgreSQL + - name: Active Record and PostgreSQL work_in_progress: true url: active_record_postgresql.html description: This guide covers PostgreSQL specific usage of Active Record. - - - name: Multiple Databases + - name: Multiple Databases url: active_record_multiple_databases.html description: This guide covers using multiple databases in your application. - - - name: Active Record Encryption + - name: Active Record Encryption url: active_record_encryption.html description: This guide covers encrypting your database information using Active Record. - - - name: Composite Primary Keys + - name: Composite Primary Keys url: active_record_composite_primary_keys.html description: This guide is an introduction to composite primary keys for database tables. -- - name: Extending Rails +- name: Extending Rails documents: - - - name: The Basics of Creating Rails Plugins + - name: The Basics of Creating Rails Plugins url: plugins.html description: This guide covers how to build a plugin to extend the functionality of Rails. - - - name: Rails on Rack + - name: Rails on Rack url: rails_on_rack.html description: This guide covers Rails integration with Rack and interfacing with other Rack components. - - - name: Creating and Customizing Rails Generators & Templates + - name: Creating and Customizing Rails Generators & Templates url: generators.html description: This guide covers the process of adding a brand new generator to your extension or providing an alternative to an element of a built-in Rails generator (such as providing alternative test stubs for the scaffold generator). - - - name: Rails Engines Overview + - name: Rails Engines Overview url: engines.html description: > Engines are packaged like miniature applications that provide additional functionality to their host applications. In this guide you will learn how to create your own engine and integrate it with a host application. - - - name: Threading and Code Execution in Rails + - name: Threading and Code Execution in Rails url: threading_and_code_execution.html description: This guide describes the considerations needed and tools available when working directly with concurrency in a Rails application. work_in_progress: true -- - name: Contributing +- name: Contributing documents: - - - name: Contributing to Ruby on Rails + - name: Contributing to Ruby on Rails url: contributing_to_ruby_on_rails.html description: Rails is not "someone else's framework". This guide covers a variety of ways that you can get involved in the ongoing development of Rails. - - - name: API Documentation Guidelines + - name: API Documentation Guidelines url: api_documentation_guidelines.html description: This guide documents the Ruby on Rails API documentation guidelines. - - - name: Guides Guidelines + - name: Guides Guidelines url: ruby_on_rails_guides_guidelines.html description: This guide documents the Ruby on Rails guides guidelines. - name: Installing Rails Core Development Dependencies url: development_dependencies_install.html description: This guide covers how to set up an environment for Ruby on Rails core development. -- - name: Policies +- name: Policies documents: - - - name: Maintenance Policy + - name: Maintenance Policy url: maintenance_policy.html description: What versions of Ruby on Rails are currently supported, and when to expect new versions. -- - name: Release Notes +- name: Release Notes documents: - - - name: Upgrading Ruby on Rails + - name: Upgrading Ruby on Rails url: upgrading_ruby_on_rails.html description: > This guide provides steps to be followed when you upgrade your applications to a newer version of Ruby on Rails. - - - name: Version 8.2 - ? + - name: Version 8.2 - ? url: 8_2_release_notes.html description: Release notes for Rails 8.2. work_in_progress: true - - - name: Version 8.1 - October 2025 + - name: Version 8.1 - October 2025 url: 8_1_release_notes.html description: Release notes for Rails 8.1. - - - name: Version 8.0 - November 2024 + - name: Version 8.0 - November 2024 url: 8_0_release_notes.html description: Release notes for Rails 8.0. - - - name: Version 7.2 - August 2024 + - name: Version 7.2 - August 2024 url: 7_2_release_notes.html description: Release notes for Rails 7.2. - - - name: Version 7.1 - October 2023 + - name: Version 7.1 - October 2023 url: 7_1_release_notes.html description: Release notes for Rails 7.1. - - - name: Version 7.0 - December 2021 + - name: Version 7.0 - December 2021 url: 7_0_release_notes.html description: Release notes for Rails 7.0. - - - name: Version 6.1 - December 2020 + - name: Version 6.1 - December 2020 url: 6_1_release_notes.html description: Release notes for Rails 6.1. - - - name: Version 6.0 - August 2019 + - name: Version 6.0 - August 2019 url: 6_0_release_notes.html description: Release notes for Rails 6.0. - - - name: Version 5.2 - April 2018 + - name: Version 5.2 - April 2018 url: 5_2_release_notes.html description: Release notes for Rails 5.2. - - - name: Version 5.1 - April 2017 + - name: Version 5.1 - April 2017 url: 5_1_release_notes.html description: Release notes for Rails 5.1. - - - name: Version 5.0 - June 2016 + - name: Version 5.0 - June 2016 url: 5_0_release_notes.html description: Release notes for Rails 5.0. - - - name: Version 4.2 - December 2014 + - name: Version 4.2 - December 2014 url: 4_2_release_notes.html description: Release notes for Rails 4.2. - - - name: Version 4.1 - April 2014 + - name: Version 4.1 - April 2014 url: 4_1_release_notes.html description: Release notes for Rails 4.1. - - - name: Version 4.0 - June 2013 + - name: Version 4.0 - June 2013 url: 4_0_release_notes.html description: Release notes for Rails 4.0. - - - name: Version 3.2 - January 2012 + - name: Version 3.2 - January 2012 url: 3_2_release_notes.html description: Release notes for Rails 3.2. - - - name: Version 3.1 - August 2011 + - name: Version 3.1 - August 2011 url: 3_1_release_notes.html description: Release notes for Rails 3.1. - - - name: Version 3.0 - August 2010 + - name: Version 3.0 - August 2010 url: 3_0_release_notes.html description: Release notes for Rails 3.0. - - - name: Version 2.3 - March 2009 + - name: Version 2.3 - March 2009 url: 2_3_release_notes.html description: Release notes for Rails 2.3. - - - name: Version 2.2 - November 2008 + - name: Version 2.2 - November 2008 url: 2_2_release_notes.html description: Release notes for Rails 2.2. diff --git a/guides/source/upgrading_from_rails_3.0_to_3.1.md b/guides/source/upgrading_from_rails_3.0_to_3.1.md new file mode 100644 index 0000000000000..af590662729df --- /dev/null +++ b/guides/source/upgrading_from_rails_3.0_to_3.1.md @@ -0,0 +1,147 @@ +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON .** + +Upgrading from Rails 3.0 to Rails 3.1 +===================================== + +This guide provides steps to be followed when you upgrade your applications from +Rails 3.0 to Rails 3.1. These steps are also available in individual release +guides. + +-------------------------------------------------------------------------------- + +Key Changes +----------- + +If your application is currently on any version of Rails older than 3.0.x, you +should upgrade to Rails 3.0 before attempting an update to Rails 3.1. + +The following changes are meant for upgrading your application to Rails 3.1.12, +the last 3.1.x version of Rails. + +### Gemfile + +Make the following changes to your `Gemfile`. + +```ruby +gem "rails", "3.1.12" +gem "mysql2" + +# Needed for the new asset pipeline +group :assets do + gem "sass-rails", "~> 3.1.7" + gem "coffee-rails", "~> 3.1.1" + gem "uglifier", ">= 1.0.3" +end + +# jQuery is the default JavaScript library in Rails 3.1 +gem "jquery-rails" +``` + +### config/application.rb + +The asset pipeline requires the following additions: + +```ruby +config.assets.enabled = true +config.assets.version = "1.0" +``` + +If your application is using an "/assets" route for a resource you may want to +change the prefix used for assets to avoid conflicts: + +```ruby +# Defaults to '/assets' +config.assets.prefix = "/asset-files" +``` + +### config/environments/development.rb + +Remove the RJS setting `config.action_view.debug_rjs = true`. + +Add these settings if you enable the asset pipeline: + +```ruby +# Do not compress assets +config.assets.compress = false + +# Expands the lines which load the assets +config.assets.debug = true +``` + +### config/environments/production.rb + +Again, most of the changes below are for the asset pipeline. You can read more +about these in the [Asset Pipeline](asset_pipeline.html) guide. + +```ruby +# Compress JavaScripts and CSS +config.assets.compress = true + +# Don't fallback to assets pipeline if a precompiled asset is missed +config.assets.compile = false + +# Generate digests for assets URLs +config.assets.digest = true + +# Defaults to Rails.root.join("public/assets") +# config.assets.manifest = YOUR_PATH + +# Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added) +# config.assets.precompile += %w( admin.js admin.css ) + +# Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies. +# config.force_ssl = true +``` + +### config/environments/test.rb + +You can help test performance with these additions to your test environment: + +```ruby +# Configure static asset server for tests with Cache-Control for performance +config.public_file_server.enabled = true +config.public_file_server.headers = { + "Cache-Control" => "public, max-age=3600" +} +``` + +### config/initializers/wrap_parameters.rb + +Add this file with the following contents, if you wish to wrap parameters into a +nested hash. This is on by default in new applications. + +```ruby +# Be sure to restart your server when you modify this file. +# This file contains settings for ActionController::ParamsWrapper which +# is enabled by default. + +# Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array. +ActiveSupport.on_load(:action_controller) do + wrap_parameters format: [:json] +end + +# Disable root element in JSON by default. +ActiveSupport.on_load(:active_record) do + self.include_root_in_json = false +end +``` + +### config/initializers/session_store.rb + +You need to change your session key to something new, or remove all sessions: + +```ruby +# in config/initializers/session_store.rb +AppName::Application.config.session_store :cookie_store, key: "SOMETHINGNEW" +``` + +or + +```bash +$ bin/rake db:sessions:clear +``` + +### Remove :cache and :concat options in asset helpers references in views + +* With the Asset Pipeline the :cache and :concat options aren't used anymore, + delete these options from your views. diff --git a/guides/source/upgrading_from_rails_3.1_to_3.2.md b/guides/source/upgrading_from_rails_3.1_to_3.2.md new file mode 100644 index 0000000000000..07b794f898e63 --- /dev/null +++ b/guides/source/upgrading_from_rails_3.1_to_3.2.md @@ -0,0 +1,73 @@ +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON .** + +Upgrading from Rails 3.1 to Rails 3.2 +===================================== + +This guide provides steps to be followed when you upgrade your applications from +Rails 3.1 to Rails 3.2. These steps are also available in individual release +guides. + +-------------------------------------------------------------------------------- + +Key Changes +----------- + +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 the latest +3.2.x version of Rails. + +### Gemfile + +Make the following changes to your `Gemfile`. + +```ruby +gem "rails", "3.2.21" + +group :assets do + gem "sass-rails", "~> 3.2.6" + gem "coffee-rails", "~> 3.2.2" + gem "uglifier", ">= 1.0.3" +end +``` + +### config/environments/development.rb + +There are a couple of new configuration settings that you should add to your +development environment: + +```ruby +# Raise exception on mass assignment protection for Active Record models +config.active_record.mass_assignment_sanitizer = :strict + +# Log the query plan for queries taking more than this (works +# with SQLite, MySQL, and PostgreSQL) +config.active_record.auto_explain_threshold_in_seconds = 0.5 +``` + +### config/environments/test.rb + +The `mass_assignment_sanitizer` configuration setting should also be added to +`config/environments/test.rb`: + +```ruby +# Raise exception on mass assignment protection for Active Record models +config.active_record.mass_assignment_sanitizer = :strict +``` + +### vendor/plugins + +Rails 3.2 deprecates `vendor/plugins` and Rails 4.0 will remove them completely. +While it's not strictly necessary as part of a Rails 3.2 upgrade, you can start +replacing any plugins by extracting them to gems and adding them to your +`Gemfile`. If you choose not to make them gems, you can move them into, say, +`lib/my_plugin/*` and add an appropriate initializer in +`config/initializers/my_plugin.rb`. + +### Active Record + +Option `:dependent => :restrict` has been removed from `belongs_to`. If you want +to prevent deleting the object if there are any associated objects, you can set +`:dependent => :destroy` and return `false` after checking for existence of +association from any of the associated object's destroy callbacks. diff --git a/guides/source/upgrading_from_rails_3.2_to_4.0.md b/guides/source/upgrading_from_rails_3.2_to_4.0.md new file mode 100644 index 0000000000000..af719ac3b5789 --- /dev/null +++ b/guides/source/upgrading_from_rails_3.2_to_4.0.md @@ -0,0 +1,492 @@ +**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON .** + +Upgrading from Rails 3.2 to Rails 4.0 +===================================== + +This guide provides steps to be followed when you upgrade your applications from +Rails 3.2 to Rails 4.0. These steps are also available in individual release +guides. + +-------------------------------------------------------------------------------- + +Key Changes +----------- + +If your application is currently on any version of Rails older than 3.2.x, you +should upgrade to Rails 3.2 before attempting one to Rails 4.0. + +The following changes are meant for upgrading your application to Rails 4.0. + +### HTTP PATCH + +Rails 4 now uses `PATCH` as the primary HTTP verb for updates when a RESTful +resource is declared in `config/routes.rb`. The `update` action is still used, +and `PUT` requests will continue to be routed to the `update` action as well. +So, if you're using only the standard RESTful routes, no changes need to be +made: + +```ruby +resources :users +``` + +```erb +<%= form_for @user do |f| %> +``` + +```ruby +class UsersController < ApplicationController + def update + # No change needed; PATCH will be preferred, and PUT will still work. + end +end +``` + +However, you will need to make a change if you are using `form_for` to update a +resource in conjunction with a custom route using the `PUT` HTTP method: + +```ruby +resources :users do + put :update_name, on: :member +end +``` + +```erb +<%= form_for [ :update_name, @user ] do |f| %> +``` + +```ruby +class UsersController < ApplicationController + def update_name + # Change needed; form_for will try to use a non-existent PATCH route. + end +end +``` + +If the action is not being used in a public API and you are free to change the +HTTP method, you can update your route to use `patch` instead of `put`: + +```ruby +resources :users do + patch :update_name, on: :member +end +``` + +`PUT` requests to `/users/:id` in Rails 4 get routed to `update` as they are +today. So, if you have an API that gets real PUT requests it is going to work. +The router also routes `PATCH` requests to `/users/:id` to the `update` action. + +If the action is being used in a public API and you can't change to HTTP method +being used, you can update your form to use the `PUT` method instead: + +```erb +<%= form_for [ :update_name, @user ], method: :put do |f| %> +``` + +For more on PATCH and why this change was made, see [this +post](https://rubyonrails.org/2012/2/26/edge-rails-patch-is-the-new-primary-http-method-for-updates) +on the Rails blog. + +#### A note about media types + +The errata for the `PATCH` verb [specifies that a 'diff' media type should be +used with `PATCH`](http://www.rfc-editor.org/errata_search.php?rfc=5789). One +such format is [JSON Patch](https://tools.ietf.org/html/rfc6902). While Rails +does not support JSON Patch natively, it's easy enough to add support: + +```ruby +# in your controller: +def update + respond_to do |format| + format.json do + # perform a partial update + @article.update params[:article] + end + + format.json_patch do + # perform sophisticated change + end + end +end +``` + +```ruby +# config/initializers/json_patch.rb +Mime::Type.register "application/json-patch+json", :json_patch +``` + +As JSON Patch was only recently made into an RFC, there aren't a lot of great +Ruby libraries yet. Aaron Patterson's [hana](https://github.com/tenderlove/hana) +is one such gem, but doesn't have full support for the last few changes in the +specification. + +### Gemfile + +Rails 4.0 removed the `assets` group from `Gemfile`. You'd need to remove that +line from your `Gemfile` when upgrading. You should also update your application +file (in `config/application.rb`): + +```ruby +# Require the gems listed in Gemfile, including any gems +# you've limited to :test, :development, or :production. +Bundler.require(*Rails.groups) +``` + +### vendor/plugins + +Rails 4.0 no longer supports loading plugins from `vendor/plugins`. You must +replace any plugins by extracting them to gems and adding them to your +`Gemfile`. If you choose not to make them gems, you can move them into, say, +`lib/my_plugin/*` and add an appropriate initializer in +`config/initializers/my_plugin.rb`. + +### Active Record + +* Rails 4.0 has removed the identity map from Active Record, due to [some + inconsistencies with + associations](https://github.com/rails/rails/commit/302c912bf6bcd0fa200d964ec2dc4a44abe328a6). + If you have manually enabled it in your application, you will have to remove + the following config that has no effect anymore: + `config.active_record.identity_map`. + +* The `delete` method in collection associations can now receive `Integer` or + `String` arguments as record ids, besides records, pretty much like the + `destroy` method does. Previously it raised + `ActiveRecord::AssociationTypeMismatch` for such arguments. From Rails 4.0 on + `delete` automatically tries to find the records matching the given ids before + deleting them. + +* In Rails 4.0 when a column or a table is renamed the related indexes are also + renamed. If you have migrations which rename the indexes, they are no longer + needed. + +* Rails 4.0 has changed `serialized_attributes` and `attr_readonly` to class + methods only. You shouldn't use instance methods since it's now deprecated. + You should change them to use class methods, e.g. `self.serialized_attributes` + to `self.class.serialized_attributes`. + +* When using the default coder, assigning `nil` to a serialized attribute will + save it to the database as `NULL` instead of passing the `nil` value through + YAML (`"--- \n...\n"`). + +* Rails 4.0 has removed `attr_accessible` and `attr_protected` feature in favor + of Strong Parameters. You can use the [Protected Attributes + gem](https://github.com/rails/protected_attributes) for a smooth upgrade path. + +* If you are not using Protected Attributes, you can remove any options related + to this gem such as `whitelist_attributes` or `mass_assignment_sanitizer` + options. + +* Rails 4.0 requires that scopes use a callable object such as a Proc or lambda: + + ```ruby + scope :active, where(active: true) + + # becomes + scope :active, -> { where active: true } + ``` + +* Rails 4.0 has deprecated `ActiveRecord::Fixtures` in favor of + `ActiveRecord::FixtureSet`. + +* Rails 4.0 has deprecated `ActiveRecord::TestCase` in favor of + `ActiveSupport::TestCase`. + +* Rails 4.0 has deprecated the old-style hash-based finder API. This means that + methods which previously accepted "finder options" no longer do. For example, + `Book.find(:all, conditions: { name: '1984' })` has been deprecated in favor + of `Book.where(name: '1984')` + +* All dynamic methods except for `find_by_...` and `find_by_...!` are + deprecated. Here's how you can handle the changes: + + * `find_all_by_...` becomes `where(...)`. + * `find_last_by_...` becomes `where(...).last`. + * `scoped_by_...` becomes `where(...)`. + * `find_or_initialize_by_...` becomes `find_or_initialize_by(...)`. + * `find_or_create_by_...` becomes `find_or_create_by(...)`. + +* Note that `where(...)` returns a relation, not an array like the old finders. + If you require an `Array`, use `where(...).to_a`. + +* These equivalent methods may not execute the same SQL as the previous + implementation. + +* To re-enable the old finders, you can use the [activerecord-deprecated_finders + gem](https://github.com/rails/activerecord-deprecated_finders). + +* Rails 4.0 has changed to default join table for `has_and_belongs_to_many` + relations to strip the common prefix off the second table name. Any existing + `has_and_belongs_to_many` relationship between models with a common prefix + must be specified with the `join_table` option. For example: + + ```ruby + class CatalogCategory < ActiveRecord::Base + has_and_belongs_to_many :catalog_products, join_table: "catalog_categories_catalog_products" + end + + class CatalogProduct < ActiveRecord::Base + has_and_belongs_to_many :catalog_categories, join_table: "catalog_categories_catalog_products" + end + ``` + +* Note that the prefix takes scopes into account as well, so relations between + `Catalog::Category` and `Catalog::Product` or `Catalog::Category` and + `CatalogProduct` need to be updated similarly. + +### Active Resource + +Rails 4.0 extracted Active Resource to its own gem. If you still need the +feature you can add the [Active Resource +gem](https://github.com/rails/activeresource) in your `Gemfile`. + +### Active Model + +* Rails 4.0 has changed how errors attach with the + `ActiveModel::Validations::ConfirmationValidator`. Now when confirmation + validations fail, the error will be attached to `:#{attribute}_confirmation` + instead of `attribute`. + +* Rails 4.0 has changed `ActiveModel::Serializers::JSON.include_root_in_json` + default value to `false`. Now, Active Model Serializers and Active Record + objects have the same default behavior. This means that you can comment or + remove the following option in the `config/initializers/wrap_parameters.rb` + file: + + ```ruby + # Disable root element in JSON by default. + # ActiveSupport.on_load(:active_record) do + # self.include_root_in_json = false + # end + ``` + +### Action Pack + +* Rails 4.0 introduces `ActiveSupport::KeyGenerator` and uses this as a base + from which to generate and verify signed cookies (among other things). + Existing signed cookies generated with Rails 3.x will be transparently + upgraded if you leave your existing `secret_token` in place and add the new + `secret_key_base`. + + ```ruby + # config/initializers/secret_token.rb + Myapp::Application.config.secret_token = "existing secret token" + Myapp::Application.config.secret_key_base = "new secret key base" + ``` + + Please note that you should wait to set `secret_key_base` until you have + 100% of your userbase on Rails 4.x and are reasonably sure you will not need + to rollback to Rails 3.x. This is because cookies signed based on the new + `secret_key_base` in Rails 4.x are not backwards compatible with Rails 3.x. + You are free to leave your existing `secret_token` in place, not set the new + `secret_key_base`, and ignore the deprecation warnings until you are + reasonably sure that your upgrade is otherwise complete. + + If you are relying on the ability for external applications or JavaScript to + be able to read your Rails app's signed session cookies (or signed cookies + in general) you should not set `secret_key_base` until you have decoupled + these concerns. + +* Rails 4.0 encrypts the contents of cookie-based sessions if `secret_key_base` + has been set. Rails 3.x signed, but did not encrypt, the contents of + cookie-based session. Signed cookies are "secure" in that they are verified to + have been generated by your app and are tamper-proof. However, the contents + can be viewed by end users, and encrypting the contents eliminates this + caveat/concern without a significant performance penalty. + + Please read [Pull Request #9978](https://github.com/rails/rails/pull/9978) + for details on the move to encrypted session cookies. + +* Rails 4.0 removed the `ActionController::Base.asset_path` option. Use the + assets pipeline feature. + +* Rails 4.0 has deprecated `ActionController::Base.page_cache_extension` option. + Use `ActionController::Base.default_static_extension` instead. + +* Rails 4.0 has removed Action and Page caching from Action Pack. You will need + to add the `actionpack-action_caching` gem in order to use `caches_action` and + the `actionpack-page_caching` to use `caches_page` in your controllers. + +* Rails 4.0 has removed the XML parameters parser. You will need to add the + `actionpack-xml_parser` gem if you require this feature. + +* Rails 4.0 changes the default `layout` lookup set using symbols or procs that + return nil. To get the "no layout" behavior, return false instead of nil. + +* Rails 4.0 changes the default memcached client from `memcache-client` to + `dalli`. To upgrade, simply add `gem "dalli"` to your `Gemfile`. + +* Rails 4.0 deprecates the `dom_id` and `dom_class` methods in controllers (they + are fine in views). You will need to include the + `ActionView::RecordIdentifier` module in controllers requiring this feature. + +* Rails 4.0 deprecates the `:confirm` option for the `link_to` helper. You + should instead rely on a data attribute (e.g. `data: { confirm: 'Are you + sure?' }`). This deprecation also concerns the helpers based on this one (such + as `link_to_if` or `link_to_unless`). + +* Rails 4.0 changed how `assert_generates`, `assert_recognizes`, and + `assert_routing` work. Now all these assertions raise `Assertion` instead of + `ActionController::RoutingError`. + +* Rails 4.0 raises an `ArgumentError` if clashing named routes are defined. This + can be triggered by explicitly defined named routes or by the `resources` + method. Here are two examples that clash with routes named `example_path`: + + ```ruby + get "one" => "test#example", as: :example + get "two" => "test#example", as: :example + ``` + + ```ruby + resources :examples + get "clashing/:id" => "test#example", as: :example + ``` + + In the first case, you can simply avoid using the same name for multiple + routes. In the second, you can use the `only` or `except` options provided + by the `resources` method to restrict the routes created as detailed in the + [Routing Guide](routing.html#restricting-the-routes-created). + +* Rails 4.0 also changed the way unicode character routes are drawn. Now you can + draw unicode character routes directly. If you already draw such routes, you + must change them, for example: + + ```ruby + get Rack::Utils.escape("こんにちは"), controller: "welcome", action: "index" + ``` + + becomes + + ```ruby + get "こんにちは", controller: "welcome", action: "index" + ``` + +* Rails 4.0 requires that routes using `match` must specify the request method. + For example: + + ```ruby + # Rails 3.x + match "/" => "root#index" + + # becomes + match "/" => "root#index", via: :get + + # or + get "/" => "root#index" + ``` + +* Rails 4.0 has removed `ActionDispatch::BestStandardsSupport` middleware, + `` already triggers standards mode per + https://msdn.microsoft.com/en-us/library/jj676915(v=vs.85).aspx and + ChromeFrame header has been moved to `config.action_dispatch.default_headers`. + + Remember you must also remove any references to the middleware from your + application code, for example: + + ```ruby + # Raise exception + config.middleware.insert_before(Rack::Lock, ActionDispatch::BestStandardsSupport) + ``` + + Also check your environment settings for + `config.action_dispatch.best_standards_support` and remove it if present. + +* Rails 4.0 allows configuration of HTTP headers by setting + `config.action_dispatch.default_headers`. The defaults are as follows: + + ```ruby + config.action_dispatch.default_headers = { + "X-Frame-Options" => "SAMEORIGIN", + "X-XSS-Protection" => "1; mode=block" + } + ``` + + Please note that if your application is dependent on loading certain pages + in a `` or `