diff options
Diffstat (limited to 'railties/guides/source')
| -rw-r--r-- | railties/guides/source/action_controller_overview.textile | 39 | ||||
| -rw-r--r-- | railties/guides/source/action_mailer_basics.textile | 6 | ||||
| -rw-r--r-- | railties/guides/source/action_view_overview.textile | 179 | ||||
| -rw-r--r-- | railties/guides/source/active_record_querying.textile | 35 | ||||
| -rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 18 | ||||
| -rw-r--r-- | railties/guides/source/association_basics.textile | 31 | ||||
| -rw-r--r-- | railties/guides/source/contributing_to_ruby_on_rails.textile | 81 | ||||
| -rw-r--r-- | railties/guides/source/debugging_rails_applications.textile | 14 | ||||
| -rw-r--r-- | railties/guides/source/getting_started.textile | 15 | ||||
| -rw-r--r-- | railties/guides/source/layouts_and_rendering.textile | 6 | ||||
| -rw-r--r-- | railties/guides/source/migrations.textile | 94 | ||||
| -rw-r--r-- | railties/guides/source/routing.textile | 4 | ||||
| -rw-r--r-- | railties/guides/source/security.textile | 26 | ||||
| -rw-r--r-- | railties/guides/source/testing.textile | 2 |
14 files changed, 164 insertions, 386 deletions
diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile index f8b586c151..3a1a4ee66e 100644 --- a/railties/guides/source/action_controller_overview.textile +++ b/railties/guides/source/action_controller_overview.textile @@ -488,45 +488,6 @@ end Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets the controller passed as an argument. The filter class has a class method +filter+ which gets run before or after the action, depending on if it's a before or after filter. Classes used as around filters can also use the same +filter+ method, which will get run in the same way. The method must +yield+ to execute the action. Alternatively, it can have both a +before+ and an +after+ method that are run before and after the action. -h3. Verification - -Verifications make sure certain criteria are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the +params+, +session+ or +flash+ hashes or that a certain HTTP method was used or that the request was made using +XMLHttpRequest+ (Ajax). The default action taken when these criteria are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. - -Here's an example of using verification to make sure the user supplies a username and a password in order to log in: - -<ruby> -class LoginsController < ApplicationController - verify :params => [:username, :password], - :render => {:action => "new"}, - :add_flash => { - :error => "Username and password required to log in" - } - - def create - @user = User.authenticate(params[:username], params[:password]) - if @user - flash[:notice] = "You're logged in" - redirect_to root_url - else - render :action => "new" - end - end -end -</ruby> - -Now the +create+ action won't run unless the "username" and "password" parameters are present, and if they're not, an error message will be added to the flash and the +new+ action will be rendered. But there's something rather important missing from the verification above: It will be used for *every* action in LoginsController, which is not what we want. You can limit which actions it will be used for with the +:only+ and +:except+ options just like a filter: - -<ruby> -class LoginsController < ApplicationController - verify :params => [:username, :password], - :render => {:action => "new"}, - :add_flash => { - :error => "Username and password required to log in" - }, - :only => :create # Run only for the "create" action -end -</ruby> - h3. Request Forgery Protection Cross-site request forgery is a type of attack in which a site tricks a user into making requests on another site, possibly adding, modifying or deleting data on that site without the user's knowledge or permission. diff --git a/railties/guides/source/action_mailer_basics.textile b/railties/guides/source/action_mailer_basics.textile index 56da360972..a6ff8f877d 100644 --- a/railties/guides/source/action_mailer_basics.textile +++ b/railties/guides/source/action_mailer_basics.textile @@ -120,7 +120,7 @@ Now that we have a user model to play with, we will just edit the +app/controlle <ruby> class UsersController < ApplicationController # POST /users - # POST /users.xml + # POST /users.json def create @user = User.new(params[:user]) @@ -130,10 +130,10 @@ class UsersController < ApplicationController UserMailer.welcome_email(@user).deliver format.html { redirect_to(@user, :notice => 'User was successfully created.') } - format.xml { render :xml => @user, :status => :created, :location => @user } + format.json { render :json => @user, :status => :created, :location => @user } else format.html { render :action => "new" } - format.xml { render :xml => @user.errors, :status => :unprocessable_entity } + format.json { render :json => @user.errors, :status => :unprocessable_entity } end end end diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 172932fdab..2b2c197f46 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -526,7 +526,7 @@ javascript_include_tag "common" # => <script type="text/javascript" src="/javascripts/common.js"></script> </ruby> -To include the Prototype and Scriptaculous JavaScript libraries in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well. +If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well. <ruby> javascript_include_tag :defaults @@ -1301,8 +1301,6 @@ h4. JavaScriptHelper Provides functionality for working with JavaScript in your views. -Rails includes the Prototype JavaScript framework and the Scriptaculous JavaScript controls and visual effects library. If you wish to use these libraries and their helpers, make sure +<%= javascript_include_tag :defaults, :cache => true %>+ is in the HEAD section of your page. This function will include the necessary JavaScript files Rails generated in the +public/javascripts+ directory. - h5. button_to_function Returns a button that'll trigger a JavaScript function using the onclick handler. Examples: @@ -1402,16 +1400,6 @@ number_with_precision(111.2345) # => 111.235 number_with_precision(111.2345, 2) # => 111.23 </ruby> -h4. PrototypeHelper - -Prototype is a JavaScript library that provides DOM manipulation, Ajax functionality, and more traditional object-oriented facilities for JavaScript. This module provides a set of helpers to make it more convenient to call functions from Prototype using Rails, including functionality to call remote Rails methods (that is, making a background request to a Rails action) using Ajax. - -To be able to use these helpers, you must first include the Prototype JavaScript framework in the HEAD of the pages with Prototype functions. - -<ruby> -javascript_include_tag 'prototype' -</ruby> - h5. evaluate_remote_response Returns +eval(request.responseText)+ which is the JavaScript function that form_remote_tag can call in +:complete+ to evaluate a multiple update return document using +update_element_function+ calls. @@ -1508,171 +1496,6 @@ would generate: return false;" type="button" value="Create" /> </html> -h5. update_page - -Yields a JavaScriptGenerator and returns the generated JavaScript code. Use this to update multiple elements on a page in an Ajax response. - -<ruby> -update_page do |page| - page.hide 'spinner' -end -</ruby> - -h5. update_page_tag - -Works like update_page but wraps the generated JavaScript in a +script+ tag. Use this to include generated JavaScript in an ERB template. - -h4. PrototypeHelper::JavaScriptGenerator::GeneratorMethods - -JavaScriptGenerator generates blocks of JavaScript code that allow you to change the content and presentation of multiple DOM elements. Use this in your Ajax response bodies, either in a +script+ tag or as plain JavaScript sent with a Content-type of "text/javascript". - -h5(#push). << - -Writes raw JavaScript to the page. - -<ruby> -page << "alert('JavaScript with Prototype.');" -</ruby> - -h5(#at). [] - -Returns a element reference by finding it through it's id in the DOM. - -<ruby> -page['blank_slate'].show # => $('blank_slate').show(); -</ruby> - -h5. alert - -Displays an alert dialog with the given message. - -<ruby> -page.alert('This message is from Rails!') -</ruby> - -h5. assign - -Assigns the JavaScript variable the given value. - -<ruby> -page.assign 'tabulated_total', @total_from_cart -</ruby> - -h5. call - -Calls the JavaScript function, optionally with the given arguments. - -<ruby> -page.call 'Element.replace', 'my_element', "My content to replace with." -</ruby> - -h5. delay - -Executes the content of the block after a delay of the number of seconds provided. - -<ruby> -page.delay(20) do - page.visual_effect :fade, 'notice' -end -</ruby> - -h5. draggable - -Creates a script.aculo.us draggable element. See ActionView::Helpers::ScriptaculousHelper for more information. - -h5. drop_receiving - -Creates a script.aculo.us drop receiving element. See ActionView::Helpers::ScriptaculousHelper for more information. - -h5. hide - -Hides the visible DOM elements with the given ids. - -<ruby> -page.hide 'person_29', 'person_9', 'person_0' -</ruby> - -h5. insert_html - -Inserts HTML at the specified position relative to the DOM element identified by the given id. - -<ruby> -page.insert_html :bottom, 'my_list', '<li>Last item</li>' -</ruby> - -h5. literal - -Returns an object whose to_json evaluates to the code provided. Use this to pass a literal JavaScript expression as an argument to another JavaScriptGenerator method. - -h5. redirect_to - -Redirects the browser to the given location using JavaScript, in the same form as +url_for+. - -<ruby> -page.redirect_to(:controller => 'accounts', :action => 'new') -</ruby> - -h5. remove - -Removes the DOM elements with the given ids from the page. - -<ruby> -page.remove 'person_23', 'person_9', 'person_2' -</ruby> - -h5. replace - -Replaces the "outer HTML" (i.e., the entire element, not just its contents) of the DOM element with the given id. - -<ruby> -page.replace 'person-45', :partial => 'person', :object => @person -</ruby> - -h5. replace_html - -Replaces the inner HTML of the DOM element with the given id. - -<ruby> -page.replace_html 'person-45', :partial => 'person', :object => @person -</ruby> - -h5(#prototype-select). select - -Returns a collection reference by finding it through a CSS pattern in the DOM. - -<ruby> -page.select('p.welcome b').first.hide # => $$('p.welcome b').first().hide(); -</ruby> - -h5. show - -Shows hidden DOM elements with the given ids. - -<ruby> -page.show 'person_6', 'person_13', 'person_223' -</ruby> - -h5. sortable - -Creates a script.aculo.us sortable element. Useful to recreate sortable elements after items get added or deleted. See ActionView::Helpers::ScriptaculousHelper for more information. - -h5. toggle - -Toggles the visibility of the DOM elements with the given ids. Example: - -<ruby> -page.toggle 'person_14', 'person_12', 'person_23' # Hides the elements -page.toggle 'person_14', 'person_12', 'person_23' # Shows the previously hidden elements -</ruby> - -h5. visual_effect - -Starts a script.aculo.us visual effect. See ActionView::Helpers::ScriptaculousHelper for more information. - - -TODO start from RecordIdentificationHelper - - h3. Localized Views Action View has the ability render different templates depending on the current locale. diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index 2f0a51e868..579a323d57 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -56,6 +56,7 @@ The methods are: * +select+ * +group+ * +order+ +* +reorder+ * +limit+ * +offset+ * +joins+ @@ -495,9 +496,9 @@ This will return single order objects for each day, but only for the last month. h3. Overriding Conditions -You can specify certain conditions to be excepted by using the +except+ method. +h4. +except+ -For example: +You can specify certain conditions to be excepted by using the +except+ method. For example: <ruby> Post.where('id > 10').limit(20).order('id asc').except(:order) @@ -509,9 +510,9 @@ The SQL that would be executed: SELECT * FROM posts WHERE id > 10 LIMIT 20 </sql> -You can also override conditions using the +only+ method. +h4. +only+ -For example: +You can also override conditions using the +only+ method. For example: <ruby> Post.where('id > 10').limit(20).order('id desc').only(:order, :where) @@ -523,6 +524,32 @@ The SQL that would be executed: SELECT * FROM posts WHERE id > 10 ORDER BY id DESC </sql> +h4. +reorder+ + +The +reorder+ method overrides the default scope order. For example: + +<ruby> +class Post < ActiveRecord::Base + .. + .. + has_many :comments, :order => 'posted_at DESC' +end + +Post.find(10).comments.reorder('name') +</ruby> + +The SQL that would be executed: + +<sql> +SELECT * FROM posts WHERE id = 10 ORDER BY name +</sql> + +In case the +reorder+ clause is not used, the SQL executed would be: + +<sql> +SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC +</sql> + h3. Readonly Objects Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception. diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index f89c83e4cd..f2170e120b 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -449,9 +449,9 @@ The predicate +in?+ tests if an object is included in another object. An +Argume Examples of +in?+: <ruby> - 1.in?([1,2]) # => true - "lo".in?("hello") # => true - 25.in?(30..50) # => false +1.in?([1,2]) # => true +"lo".in?("hello") # => true +25.in?(30..50) # => false </ruby> NOTE: Defined in +active_support/core_ext/object/inclusion.rb+. @@ -541,9 +541,9 @@ The default value can be also specified with a block, which is called in the con <ruby> class User attr_accessor :name, :surname - attr_accessor_with_default(:full_name) { - [name, surname].compact.join(" ") - } + attr_accessor_with_default(:full_name) do + [name, surname].compact.join(" ") + end end u = User.new @@ -1223,7 +1223,7 @@ NOTE: Defined in +active_support/core_ext/string/output_safety.rb+. h4. +squish+ -The method +String#squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each: +The method +squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each: <ruby> " \n foo\n\r \t bar \n".squish # => "foo bar" @@ -1996,11 +1996,11 @@ Active Support augments the API of arrays to ease certain ways of accessing them [].to(7) # => [] </ruby> -Similarly, +from+ returns the tail from the element at the passed index on: +Similarly, +from+ returns the tail from the element at the passed index to the end. If the index is greater than the length of the array, it returns an empty array. <ruby> %w(a b c d).from(2) # => %w(c d) -%w(a b c d).from(10) # => nil +%w(a b c d).from(10) # => [] [].from(0) # => [] </ruby> diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index e5b8c73c43..94dce1b97b 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -229,7 +229,7 @@ The corresponding migration might look like this: <ruby> class CreateSuppliers < ActiveRecord::Migration - def self.up + def change create_table :suppliers do |t| t.string :name t.timestamps @@ -241,11 +241,6 @@ class CreateSuppliers < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :accounts - drop_table :suppliers - end end </ruby> @@ -314,7 +309,7 @@ If you have an instance of the +Picture+ model, you can get to its parent via +@ <ruby> class CreatePictures < ActiveRecord::Migration - def self.up + def change create_table :pictures do |t| t.string :name t.integer :imageable_id @@ -322,10 +317,6 @@ class CreatePictures < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :pictures - end end </ruby> @@ -333,17 +324,13 @@ This migration can be simplified by using the +t.references+ form: <ruby> class CreatePictures < ActiveRecord::Migration - def self.up + def change create_table :pictures do |t| t.string :name t.references :imageable, :polymorphic => true t.timestamps end end - - def self.down - drop_table :pictures - end end </ruby> @@ -413,17 +400,13 @@ This declaration needs to be backed up by the proper foreign key declaration on <ruby> class CreateOrders < ActiveRecord::Migration - def self.up + def change create_table :orders do |t| t.datetime :order_date t.string :order_number t.integer :customer_id end end - - def self.down - drop_table :orders - end end </ruby> @@ -451,16 +434,12 @@ These need to be backed up by a migration to create the +assemblies_parts+ table <ruby> class CreateAssemblyPartJoinTable < ActiveRecord::Migration - def self.up + def change create_table :assemblies_parts, :id => false do |t| t.integer :assembly_id t.integer :part_id end end - - def self.down - drop_table :assemblies_parts - end end </ruby> diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile index cbc4acfeca..cb09b180a2 100644 --- a/railties/guides/source/contributing_to_ruby_on_rails.textile +++ b/railties/guides/source/contributing_to_ruby_on_rails.textile @@ -2,7 +2,7 @@ h2. Contributing to Ruby on Rails This guide covers ways in which _you_ can become a part of the ongoing development of Ruby on Rails. After reading it, you should be familiar with: -* Using Lighthouse to report issues +* Using GitHub to report issues * Cloning master and running the test suite * Helping to resolve existing issues * Contributing to the Ruby on Rails documentation @@ -14,29 +14,25 @@ endprologue. h3. Reporting an Issue -Ruby on Rails uses a "Lighthouse project":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/ to track issues (primarily bugs and contributions of new code). If you've found a bug in Ruby on Rails, this is the place to start. You'll need to create a (free) Lighthouse account in order to comment on issues or to upload patches. +Ruby on Rails uses "GitHub Issue Tracking":https://github.com/rails/rails/issues to track issues (primarily bugs and contributions of new code). If you've found a bug in Ruby on Rails, this is the place to start. You'll need to create a (free) GitHub account in order to either submit an issue, comment on them or create pull requests. NOTE: Bugs in the most recent released version of Ruby on Rails are likely to get the most attention. Also, the Rails core team is always interested in feedback from those who can take the time to test _edge Rails_ (the code for the version of Rails that is currently under development). Later in this guide you'll find out how to get edge Rails for testing. h4. Creating a Bug Report -If you've found a problem in Ruby on Rails which is not a security risk do a search in Lighthouse in case it was already reported. If you find no ticket addressing it you can "add a new one":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/new. (See the next section for reporting security issues.) +If you've found a problem in Ruby on Rails which is not a security risk do a search in GitHub Issues in case it was already reported. If you find no issue addressing it you can "add a new one":https://github.com/rails/rails/issues/new. (See the next section for reporting security issues.) -At the minimum, your ticket needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need to at least post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself - and others - to replicate the bug and figure out a fix. +At the minimum, your issue report needs a title and descriptive text. But that's only a minimum. You should include as much relevant information as possible. You need to at least post the code sample that has the issue. Even better is to include a unit test that shows how the expected behavior is not occurring. Your goal should be to make it easy for yourself - and others - to replicate the bug and figure out a fix. -You shouldn't assign the bug to a particular core developer unless you know for sure which developer will be handling that issue. The core team periodically reviews issues and assigns developers and milestones to them. - -You should set tags for your issue. Use the "bug" tag for a bug report, and add the "patch" tag if you are attaching a patch. Try to find some relevant tags from the existing tag list (which will appear as soon as you start typing in the "Choose some tags" textbox), rather than creating new tags. - -Then don't get your hopes up. Unless you have a "Code Red, Mission Critical, The World is Coming to an End" kind of bug, you're creating this ticket in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the ticket automatically will see any activity or that others will jump to fix it. Creating a ticket like this is mostly to help yourself start on the path of fixing the problem and for others to confirm it with a "I'm having this problem too" comment. +Then don't get your hopes up. Unless you have a "Code Red, Mission Critical, The World is Coming to an End" kind of bug, you're creating this issue report in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the issue report will automatically see any activity or that others will jump to fix it. Creating a issue like this is mostly to help yourself start on the path of fixing the problem and for others to confirm it with a "I'm having this problem too" comment. h4. Special Treatment for Security Issues -WARNING: Please do not report security vulnerabilities on public Lighthouse tickets. The "Rails security policy page":http://rubyonrails.org/security details the procedure to follow for security issues. +WARNING: Please do not report security vulnerabilities with public GitHub issue reports. The "Rails security policy page":http://rubyonrails.org/security details the procedure to follow for security issues. h4. What About Feature Requests? -Please don't put "feature request" tickets into Lighthouse. If there's a new feature that you want to see added to Ruby on Rails, you'll need to write the code yourself - or convince someone else to partner with you to write the code. Later in this guide you'll find detailed instructions for proposing a patch to Ruby on Rails. If you enter a wishlist item in Lighthouse with no code, you can expect it to be marked "invalid" as soon as it's reviewed. +Please don't put "feature request" items into GitHub Issues. If there's a new feature that you want to see added to Ruby on Rails, you'll need to write the code yourself - or convince someone else to partner with you to write the code. Later in this guide you'll find detailed instructions for proposing a patch to Ruby on Rails. If you enter a wishlist item in GitHub Issues with no code, you can expect it to be marked "invalid" as soon as it's reviewed. h3. Running the Test Suite @@ -48,7 +44,7 @@ Ruby on Rails uses git for source code control. The "git homepage":http://git-sc * "Everyday Git":http://www.kernel.org/pub/software/scm/git/docs/everyday.html will teach you just enough about git to get by. * The "PeepCode screencast":https://peepcode.com/products/git on git ($9) is easier to follow. -* "GitHub":https://github.com/guides/home offers links to a variety of git resources. +* "GitHub":http://help.github.com offers links to a variety of git resources. * "Pro Git":http://progit.org/book/ is an entire book about git with a Creative Commons license. h4. Clone the Ruby on Rails Repository @@ -216,11 +212,11 @@ TIP: You may want to "put your git branch name in your shell prompt":http://qugs h3. Helping to Resolve Existing Issues -As a next step beyond reporting issues, you can help the core team resolve existing issues. If you check the "open tickets":https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets?q=state%3Aopen list in Lighthouse, you'll find lots of issues already requiring attention. What can you do for these? Quite a bit, actually: +As a next step beyond reporting issues, you can help the core team resolve existing issues. If you check the "Everyone's Issues":https://github.com/rails/rails/issues?sort=created&direction=desc&state=open&page=1 list in GitHub Issues, you'll find lots of issues already requiring attention. What can you do for these? Quite a bit, actually: h4. Verifying Bug Reports -For starters, it helps to just verify bug reports. Can you reproduce the reported issue on your own computer? If so, you can add a comment to the ticket saying that you're seeing the same thing. +For starters, it helps to just verify bug reports. Can you reproduce the reported issue on your own computer? If so, you can add a comment to the issue saying that you're seeing the same thing. If something is very vague, can you help squish it down into something specific? Maybe you can provide additional information to help reproduce a bug, or eliminate needless steps that aren't required to help demonstrate the problem. @@ -230,38 +226,39 @@ Anything you can do to make bug reports more succinct or easier to reproduce is h4. Testing Patches -You can also help out by examining patches that have been submitted to Ruby on Rails via Lighthouse. To apply someone's changes you need to first create a dedicated branch: +You can also help out by examining pull requests that have been submitted to Ruby on Rails via GitHub. To apply someone's changes you need to first create a dedicated branch: <shell> $ git checkout -b testing_branch </shell> -Then you can apply their patch: +Then you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to the master branch located at https://github.com/JohnSmith/rails. <shell> -$ git am their-patch-file.diff +$ git remote add JohnSmith git://github.com/JohnSmith/rails.git +$ git pull JohnSmith master </shell> -After applying a patch, test it out! Here are some things to think about: +After applying their branch, test it out! Here are some things to think about: -* Does the patch actually work? +* Does the change actually work? * Are you happy with the tests? Can you follow what they're testing? Are there any tests missing? * Does it have proper documentation coverage? Should documentation elsewhere be updated? * Do you like the implementation? Can you think of a nicer or faster way to implement a part of their change? -Once you're happy that the patch contains a good change, comment on the Lighthouse ticket indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like: +Once you're happy that the pull request contains a good change, comment on the GitHub issue indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like: <blockquote> I like the way you've restructured that code in generate_finder_sql, much nicer. The tests look good too. </blockquote> -If your comment simply says "+1", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the patch. Once three people have approved it, add the "verified" tag. This will bring it to the attention of a core team member who will review the changes looking for the same kinds of things. +If your comment simply says "+1", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the pull request. h3. Contributing to the Rails Documentation Ruby on Rails has two main sets of documentation: The guides help you to learn Ruby on Rails, and the API is a reference. -You can create a ticket in Lighthouse to fix or expand documentation. However, if you're confident about your changes you can push them yourself directly via "docrails":https://github.com/lifo/docrails/tree/master. docrails is a branch with an *open commit policy* and public write access. Commits to docrails are still reviewed, but that happens after they are pushed. docrails is merged with master regularly, so you are effectively editing the Ruby on Rails documentation. +You can create an issue in GitHub issues to fix or expand documentation. However, if you're confident about your changes you can push them yourself directly via "docrails":https://github.com/lifo/docrails/tree/master. docrails is a branch with an *open commit policy* and public write access. Commits to docrails are still reviewed, but that happens after they are pushed. docrails is merged with master regularly, so you are effectively editing the Ruby on Rails documentation. When working with documentation, please take into account the "API Documentation Guidelines":api_documentation_guidelines.html and the "Ruby on Rails Guides Guidelines":ruby_on_rails_guides_guidelines.html. @@ -314,20 +311,14 @@ You should not be the only person who looks at the code before you submit it. Yo You might also want to check out the "RailsBridge BugMash":http://wiki.railsbridge.org/projects/railsbridge/wiki/BugMash as a way to get involved in a group effort to improve Rails. This can help you get started and help check your code when you're writing your first patches. -h4. Create a Lighthouse Ticket - -Now create a ticket for your patch. Go to the "new ticket":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/new page at Lighthouse. Fill in a reasonable title and description, as well as tag the ticket with the ‘patch’ tag and whatever other subject area tags make sense. Write down your ticket number, for you will need it in the following step. - h4. Commit Your Changes When you're happy with the code on your computer, you need to commit the changes to git: <shell> -$ git commit -a -m "Here is a commit message [#ticket_number state:committed]" +$ git commit -a -m "Here is a commit message on what I changed in this commit" </shell> -NOTE: By adding '[#ticket_number state:committed]' at the end of your commit message, the ticket will automatically change its status to commited once your patch is pushed to the repository. - h4. Update master It’s pretty likely that other changes to master have happened while you were working. Go get them: @@ -346,33 +337,29 @@ $ git rebase master No conflicts? Tests still pass? Change still seems reasonable to you? Then move on. -h4. Create a Patch - -Now you can create a patch file to share with other developers (and with the core team). Still in your branch, run +h4. Fork -<shell> -$ git commit -a -$ git format-patch master --stdout > my_new_patch.diff -</shell> - -Open the diff file in your text editor of choice to sanity check the results, and make sure that no unintended changes crept in. +Navigate to the Rails "GitHub repository":https://github.com/rails/rails and press "Fork" in the upper right hand corner. -You can also perform an extra check by applying the patch to a different dedicated branch: +Add the new remote to your local repository on your local machine: <shell> -$ git checkout -b testing_branch -$ git apply --check my_new_patch.diff +$ git remote add mine https://<your user name>@github.com/<your user name>/rails.git </shell> -Please make sure the patch does not introduce whitespace errors: +Push to your remote: <shell> -$ git apply --whitespace=error-all my_new_patch.diff +$ git push mine master </shell> -h4. Attach your Patch to the Lighthouse Ticket +h4. Issue a Pull Request + +Navigate to the Rails repository you just pushed to (e.g. https://github.com/<your user name>/rails) and press "Pull Request" in the upper right hand corner. + +Ensure the changesets you introduced are included in the "Commits" tab and that the "Files Changed" incorporate all of your changes. -Now you need to update the ticket by attaching the patch file you just created. +Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request." Rails Core will be notified about your submission. h4. Get Some Feedback @@ -390,9 +377,9 @@ All contributions, either via master or docrails, get credit in "Rails Contribut h3. Changelog -* April 14, 2001: Modified Contributing to the Rails Code section to add '[#ticket_number state:commited]' on patches commit messages by "Sebastian Martinez":http://wyeworks.com +* April 29, 2011: Reflect GitHub Issues and Pull Request workflow by "Dan Pickett":http://www.enlightsolutions.com +* April 14, 2011: Modified Contributing to the Rails Code section to add '[#ticket_number state:commited]' on patches commit messages by "Sebastian Martinez":http://wyeworks.com * December 28, 2010: Complete revision by "Xavier Noria":credits.html#fxn * April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com * August 1, 2009: Updates/amplifications by "Mike Gunderloy":credits.html#mgunderloy * March 2, 2009: Initial draft by "Mike Gunderloy":credits.html#mgunderloy - diff --git a/railties/guides/source/debugging_rails_applications.textile b/railties/guides/source/debugging_rails_applications.textile index 477ff29dbd..6f028805d6 100644 --- a/railties/guides/source/debugging_rails_applications.textile +++ b/railties/guides/source/debugging_rails_applications.textile @@ -279,14 +279,14 @@ This command shows you where you are in the code by printing 10 lines centered a [1, 10] in /PathToProject/posts_controller.rb 1 class PostsController < ApplicationController 2 # GET /posts - 3 # GET /posts.xml + 3 # GET /posts.json 4 def index 5 debugger => 6 @posts = Post.all 7 8 respond_to do |format| 9 format.html # index.html.erb - 10 format.xml { render :xml => @posts } + 10 format.json { render :json => @posts } </shell> If you repeat the +list+ command, this time using just +l+, the next ten lines of the file will be printed out. @@ -298,7 +298,7 @@ If you repeat the +list+ command, this time using just +l+, the next ten lines o 12 end 13 14 # GET /posts/1 - 15 # GET /posts/1.xml + 15 # GET /posts/1.json 16 def show 17 @post = Post.find(params[:id]) 18 @@ -315,14 +315,14 @@ On the other hand, to see the previous ten lines you should type +list-+ (or +l- [1, 10] in /PathToProject/posts_controller.rb 1 class PostsController < ApplicationController 2 # GET /posts - 3 # GET /posts.xml + 3 # GET /posts.json 4 def index 5 debugger 6 @posts = Post.all 7 8 respond_to do |format| 9 format.html # index.html.erb - 10 format.xml { render :xml => @posts } + 10 format.json { render :json => @posts } </shell> This way you can move inside the file, being able to see the code above and over the line you added the +debugger+. @@ -333,14 +333,14 @@ Finally, to see where you are in the code again you can type +list=+ [1, 10] in /PathToProject/posts_controller.rb 1 class PostsController < ApplicationController 2 # GET /posts - 3 # GET /posts.xml + 3 # GET /posts.json 4 def index 5 debugger => 6 @posts = Post.all 7 8 respond_to do |format| 9 format.html # index.html.erb - 10 format.xml { render :xml => @posts } + 10 format.json { render :json => @posts } </shell> h4. The Context diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 366df9cd84..a826a33120 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -378,7 +378,7 @@ If you look in the +db/migrate/20100207214725_create_posts.rb+ file (remember, y <ruby> class CreatePosts < ActiveRecord::Migration - def self.up + def change create_table :posts do |t| t.string :name t.string :title @@ -387,14 +387,10 @@ class CreatePosts < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :posts - end end </ruby> -The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date. The +up+ command in this case creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. +The above migration creates a method name +change+ which will be called when you run this migration. The action defined in that method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it at later date. By default, when you run this migration it will creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. At this point, you can use a rake command to run the migration: @@ -807,7 +803,7 @@ In addition to the model, Rails has also made a migration to create the correspo <ruby> class CreateComments < ActiveRecord::Migration - def self.up + def change create_table :comments do |t| t.string :commenter t.text :body @@ -818,10 +814,6 @@ class CreateComments < ActiveRecord::Migration add_index :comments, :post_id end - - def self.down - drop_table :comments - end end </ruby> @@ -1458,6 +1450,7 @@ Two very common sources of data that are not UTF-8: h3. Changelog +* April 26, 2011: Changed migration code from +up+, +down+ pair to +change+ method "Prem Sichanugrist":"http://sikachu.com" * April 11, 2011: Changed scaffold_controller generator to create format block for JSON instead of XML "Sebastian Martinez":http://www.wyeworks.com * August 30, 2010: Minor editing after Rails 3 release by "Joost Baaij":http://www.spacebabies.nl * July 12, 2010: Fixes, editing and updating of code samples by "Jaime Iniesta":http://jaimeiniesta.com diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile index 620df970dc..d67668df91 100644 --- a/railties/guides/source/layouts_and_rendering.textile +++ b/railties/guides/source/layouts_and_rendering.textile @@ -695,13 +695,13 @@ To include +http://example.com/main.js+: <%= javascript_include_tag "http://example.com/main.js" %> </erb> -The +:defaults+ option loads jQuery by default: +If the application does not use the asset pipeline, the +:defaults+ option loads jQuery by default: <erb> <%= javascript_include_tag :defaults %> </erb> -If the application was generated with "-j prototype" <tt>:defaults</tt> loads Prototype and Scriptaculous. And you can in any case override the expansion in <tt>config/application.rb</tt>: +And you can in any case override the expansion in <tt>config/application.rb</tt>: <ruby> config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js) @@ -709,7 +709,7 @@ config.action_view.javascript_expansions[:defaults] = %w(foo.js bar.js) When using <tt>:defaults</tt>, if an <tt>application.js</tt> file exists in <tt>public/javascripts</tt> it will be included as well at then end. -The +:all+ option loads every JavaScript file in +public/javascripts+: +Also, the +:all+ option loads every JavaScript file in +public/javascripts+: <erb> <%= javascript_include_tag :all %> diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile index bf5d4d3e4d..27f8a9303e 100644 --- a/railties/guides/source/migrations.textile +++ b/railties/guides/source/migrations.textile @@ -21,7 +21,7 @@ Before I dive into the details of a migration, here are a few examples of the so <ruby> class CreateProducts < ActiveRecord::Migration - def self.up + def up create_table :products do |t| t.string :name t.text :description @@ -30,7 +30,7 @@ class CreateProducts < ActiveRecord::Migration end end - def self.down + def down drop_table :products end end @@ -42,14 +42,14 @@ Migrations are not limited to changing the schema. You can also use them to fix <ruby> class AddReceiveNewsletterToUsers < ActiveRecord::Migration - def self.up + def up change_table :users do |t| t.boolean :receive_newsletter, :default => false end User.update_all ["receive_newsletter = ?", true] end - def self.down + def down remove_column :users, :receive_newsletter end end @@ -58,6 +58,21 @@ end This migration adds a +receive_newsletter+ column to the +users+ table. We want it to default to +false+ for new users, but existing users are considered to have already opted in, so we use the User model to set the flag to +true+ for existing users. +Rails 3.1 makes migrations smarter by providing a new <tt>change</tt> method. This method is preferred for writing constructive migrations (adding columns or tables). The migration knows how to migrate your database and reverse it when the migration is rolled back without the need to write a separate +down+ method. + +<ruby> +class CreateProducts < ActiveRecord::Migration + def change + create_table :products do |t| + t.string :name + t.text :description + + t.timestamps + end + end +end +</ruby> + NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations. h4. Migrations are Classes @@ -116,7 +131,7 @@ will create a migration that looks like this <ruby> class CreateProducts < ActiveRecord::Migration - def self.up + def change create_table :products do |t| t.string :name t.text :description @@ -124,10 +139,6 @@ class CreateProducts < ActiveRecord::Migration t.timestamps end end - - def self.down - drop_table :products - end end </ruby> @@ -146,10 +157,7 @@ This will create an empty but appropriately named migration: <ruby> class AddPartNumberToProducts < ActiveRecord::Migration - def self.up - end - - def self.down + def change end end </ruby> @@ -164,13 +172,9 @@ will generate <ruby> class AddPartNumberToProducts < ActiveRecord::Migration - def self.up + def change add_column :products, :part_number, :string end - - def self.down - remove_column :products, :part_number - end end </ruby> @@ -184,11 +188,11 @@ generates <ruby> class RemovePartNumberFromProducts < ActiveRecord::Migration - def self.up + def up remove_column :products, :part_number end - def self.down + def down add_column :products, :part_number, :string end end @@ -204,20 +208,17 @@ generates <ruby> class AddDetailsToProducts < ActiveRecord::Migration - def self.up + def change add_column :products, :part_number, :string add_column :products, :price, :decimal end - - def self.down - remove_column :products, :price - remove_column :products, :part_number - end end </ruby> As always, what has been generated for you is just a starting point. You can add or remove from it as you see fit. +NOTE: The generated migration file for destructive migrations will still be old-style using the +up+ and +down+ methods. This is because Rails doesn't know the original data types defined when you made the original changes. + h3. Writing a Migration Once you have created your migration using one of the generators it's time to get to work! @@ -337,6 +338,21 @@ If the helpers provided by Active Record aren't enough you can use the +execute+ For more details and examples of individual methods check the API documentation, in particular the documentation for "<tt>ActiveRecord::ConnectionAdapters::SchemaStatements</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "<tt>ActiveRecord::ConnectionAdapters::TableDefinition</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html (which provides the methods available on the object yielded by +create_table+) and "<tt>ActiveRecord::ConnectionAdapters::Table</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+). +h4. Writing Your +change+ Method + +The +change+ method removes the need to write both +up+ and +down+ methods in those cases that Rails know how to revert the changes automatically. Currently, the +change+ method supports only these migration definitions: + +* +add_column+ +* +add_index+ +* +add_timestamp+ +* +create_table+ +* +remove_timestamps+ +* +rename_column+ +* +rename_index+ +* +rename_table+ + +If you're going to use other methods, you'll have to write the +up+ and +down+ methods normally. + h4. Writing Your +down+ Method The +down+ method of your migration should revert the transformations done by the +up+ method. In other words the database schema should be unchanged if you do an +up+ followed by a +down+. For example if you create a table in the +up+ method you should drop it in the +down+ method. It is wise to do things in precisely the reverse order to in the +up+ method. For example @@ -344,7 +360,7 @@ The +down+ method of your migration should revert the transformations done by th <ruby> class ExampleMigration < ActiveRecord::Migration - def self.up + def up create_table :products do |t| t.references :category end @@ -361,7 +377,7 @@ class ExampleMigration < ActiveRecord::Migration rename_column :users, :email, :email_address end - def self.down + def down rename_column :users, :email_address, :email remove_column :users, :home_page_url execute "ALTER TABLE products DROP FOREIGN KEY fk_products_categories" @@ -369,9 +385,8 @@ class ExampleMigration < ActiveRecord::Migration end end </ruby> -Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be -displayed saying that it can't be done. +Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be displayed saying that it can't be done. h3. Running Migrations @@ -449,7 +464,7 @@ For example, this migration <ruby> class CreateProducts < ActiveRecord::Migration - def self.up + def change suppress_messages do create_table :products do |t| t.string :name @@ -465,10 +480,6 @@ class CreateProducts < ActiveRecord::Migration 250 end end - - def self.down - drop_table :products - end end </ruby> @@ -499,11 +510,7 @@ class AddPartNumberToProducts < ActiveRecord::Migration class Product < ActiveRecord::Base end - def self.up - ... - end - - def self.down + def change ... end end @@ -519,15 +526,11 @@ class AddPartNumberToProducts < ActiveRecord::Migration class Product < ActiveRecord::Base end - def self.up + def change add_column :product, :part_number, :string Product.reset_column_information ... end - - def self.down - ... - end end </ruby> @@ -590,5 +593,6 @@ Although Active Record does not provide any tools for working directly with such h3. Changelog +* April 26, 2011: change generated +up+ and +down+ methods to +change+ method, and describe detail about +change+ method by "Prem Sichanugrist":http://sikachu.com * July 15, 2010: minor typos corrected by "Jaime Iniesta":http://jaimeiniesta.com * September 14, 2008: initial version by "Frederick Cheung":credits.html#fcheung diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 43c08165dc..99fdcee68a 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -391,7 +391,7 @@ NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/ </ruby> -TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id => /[^\/]<plus>/+ allows anything except a slash. +TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash. h4. Static Segments @@ -660,7 +660,7 @@ end NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context. -TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id => /[^\/]+/+ allows anything except a slash. +TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash. h4. Overriding the Named Helpers diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index f87ffdb20d..8c408ec06b 100644 --- a/railties/guides/source/security.textile +++ b/railties/guides/source/security.textile @@ -211,15 +211,7 @@ The HTTP protocol basically provides two main types of requests - GET and POST ( If your web application is RESTful, you might be used to additional HTTP verbs, such as PUT or DELETE. Most of today‘s web browsers, however do not support them - only GET and POST. Rails uses a hidden +_method+ field to handle this barrier. -_(highlight)The verify method in a controller can make sure that specific actions may not be used over GET_. Here is an example to verify the use of the transfer action over POST. If the action comes in using any other verb, it redirects to the list action. - -<ruby> -verify :method => :post, :only => [:transfer], :redirect_to => {:action => :list} -</ruby> - -With this precaution, the attack from above will not work, because the browser sends a GET request for images, which will not be accepted by the web application. - -But this was only the first step, because _(highlight)POST requests can be sent automatically, too_. Here is an example for a link which displays www.harmless.com as destination in the browser's status bar. In fact it dynamically creates a new form that sends a POST request. +_(highlight)POST requests can be sent automatically, too_. Here is an example for a link which displays www.harmless.com as destination in the browser's status bar. In fact it dynamically creates a new form that sends a POST request. <html> <a href="http://www.harmless.com/" onclick=" @@ -441,7 +433,7 @@ params[:user] # => {:name => "ow3ned", :admin => true} @user.admin # => true </ruby> -When assigning attributes in Active Record using +new+, +attributes=+, or +update_attributes+ the :default scope will be used. To assign attributes using different scopes you should use +assign_attributes+ which accepts an optional :as options parameter. If no :as option is provided then the :default scope will be used. You can also bypass mass-assignment security by using the +:without_protection+ option. Here is an example: +When assigning attributes in Active Record using +attributes=+, or +update_attributes+ the :default scope will be used. To assign attributes using different scopes you should use +assign_attributes+ which accepts an optional :as options parameter. If no :as option is provided then the :default scope will be used. You can also bypass mass-assignment security by using the +:without_protection+ option. Here is an example: <ruby> @user = User.new @@ -459,7 +451,19 @@ When assigning attributes in Active Record using +new+, +attributes=+, or +updat @user.is_admin # => true </ruby> -A more paranoid technique to protect your whole project would be to enforce that all models define their accessible attributes. This can be easily achieved with a very simple application config option of: +In a similar way, +new+, +create+ and <tt>create!</tt> methods respect mass-assignment security and accepts either +:as+ or +:without_protection+ options. For example: + +<ruby> +@user = User.new({ :name => 'Sebastian', :is_admin => true }, :as => :admin) +@user.name # => Sebastian +@user.is_admin # => true + +@user = User.create({ :name => 'Sebastian', :is_admin => true }, :without_protection => true) +@user.name # => Sebastian +@user.is_admin # => true +</ruby> + +A more paranoid technique to protect your whole project would be to enforce that all models define their accessible attributes. This can be easily achieved with a very simple application config option of: <ruby> config.active_record.whitelist_attributes = true diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile index 9b1ef22b97..efa2bbdca6 100644 --- a/railties/guides/source/testing.textile +++ b/railties/guides/source/testing.textile @@ -941,7 +941,7 @@ h3. Other Testing Approaches The built-in +test/unit+ based testing is not the only way to test Rails applications. Rails developers have come up with a wide variety of other approaches and aids for testing, including: * "NullDB":http://avdi.org/projects/nulldb/, a way to speed up testing by avoiding database use. -* "Factory Girl":https://github.com/thoughtbot/factory_girl/tree/master, as replacement for fixtures. +* "Factory Girl":https://github.com/thoughtbot/factory_girl/tree/master, a replacement for fixtures. * "Machinist":https://github.com/notahat/machinist/tree/master, another replacement for fixtures. * "Shoulda":http://www.thoughtbot.com/projects/shoulda, an extension to +test/unit+ with additional helpers, macros, and assertions. * "RSpec":http://rspec.info/, a behavior-driven development framework |