diff options
Diffstat (limited to 'guides/source/contributing_to_ruby_on_rails.textile')
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.textile | 111 |
1 files changed, 71 insertions, 40 deletions
diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index dd43ef795f..4bb4e3b546 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -36,20 +36,26 @@ Please don't put "feature request" items into GitHub Issues. If there's a new fe If you'd like feedback on an idea for a feature before doing the work for make a patch, please send an email to the "rails-core mailing list":https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core. You might get no response, which means that everyone is indifferent. You might find someone who's also interested in building that feature. You might get a "This won't be accepted." But it's the proper place to discuss new ideas. GitHub Issues are not a particularly good venue for the sometimes long and involved discussions new features require. -h3. Running the Test Suite +h3. Setting Up a Development Environment To move on from submitting bugs to helping resolve existing issues or contributing your own code to Ruby on Rails, you _must_ be able to run its test suite. In this section of the guide you'll learn how to set up the tests on your own computer. -h4. Install Git +h4. The Easy Way -Ruby on Rails uses git for source code control. The "git homepage":http://git-scm.com/ has installation instructions. There are a variety of resources on the net that will help you get familiar with git: +The easiest way to get a development environment ready to hack is to use the "Rails development box":https://github.com/rails/rails-dev-box. -* "Everyday Git":http://schacon.github.com/git/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":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. The Hard Way -h4. Clone the Ruby on Rails Repository +h5. Install Git + +Ruby on Rails uses Git for source code control. The "Git homepage":http://git-scm.com/ has installation instructions. There are a variety of resources on the net that will help you get familiar with Git: + +* "Everyday Git":http://schacon.github.com/git/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":http://help.github.com offers links to a variety of Git resources. +* "Pro Git":http://git-scm.com/book is an entire book about Git with a Creative Commons license. + +h5. Clone the Ruby on Rails Repository Navigate to the folder where you want the Ruby on Rails source code (it will create its own +rails+ subdirectory) and run: @@ -58,7 +64,7 @@ $ git clone git://github.com/rails/rails.git $ cd rails </shell> -h4. Set up and Run the Tests +h5. Set up and Run the Tests The test suite must pass with any submitted code. No matter whether you are writing a new patch, or evaluating someone else's, you need to be able to run the tests. @@ -74,7 +80,7 @@ If you are on Fedora or CentOS, you can run $ sudo yum install libxml2 libxml2-devel libxslt libxslt-devel </shell> -If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions "here":http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos . +If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions at the "Red Hat/CentOS section of the Nokogiri tutorials":http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos . Also, SQLite3 and its development files for the +sqlite3-ruby+ gem -- in Ubuntu you're done with just @@ -128,36 +134,17 @@ $ cd actionpack $ bundle exec ruby -Itest test/template/form_helper_test.rb </shell> -h4. Warnings - -The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. - -As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: - -<shell> -$ RUBYOPT=-W0 bundle exec rake test -</shell> - -h4. Testing Active Record +h5. Active Record Setup The test suite of Active Record attempts to run four times: once for SQLite3, once for each of the two MySQL gems (+mysql+ and +mysql2+), and once for PostgreSQL. We are going to see now how to set up the environment for them. WARNING: If you're working with Active Record code, you _must_ ensure that the tests pass for at least MySQL, PostgreSQL, and SQLite3. Subtle differences between the various adapters have been behind the rejection of many patches that looked OK when tested only against MySQL. -h5. Database Configuration +h6. Database Configuration The Active Record test suite requires a custom config file: +activerecord/test/config.yml+. An example is provided in +activerecord/test/config.example.yml+ which can be copied and used as needed for your environment. -h5. SQLite3 - -The gem +sqlite3-ruby+ does not belong to the "db" group. Indeed, if you followed the instructions above you're ready. This is how you run the Active Record test suite only for SQLite3: - -<shell> -$ cd activerecord -$ bundle exec rake test_sqlite3 -</shell> - -h5. MySQL and PostgreSQL +h6. MySQL and PostgreSQL To be able to run the suite for MySQL and PostgreSQL we need their gems. Install first the servers, their client libraries, and their development files. In Ubuntu just run @@ -217,6 +204,15 @@ NOTE: You'll see the following warning (or localized warning) during activating If you’re using another database, check the file +activerecord/test/config.yml+ or +activerecord/test/config.example.yml+ for default connection information. You can edit +activerecord/test/config.yml+ to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails. +h3. Testing Active Record + +This is how you run the Active Record test suite only for SQLite3: + +<shell> +$ cd activerecord +$ bundle exec rake test_sqlite3 +</shell> + You can now run the tests as you did for +sqlite3+. The tasks are respectively <shell> @@ -225,7 +221,7 @@ test_mysql2 test_postgresql </shell> -As we mentioned before +Finally, <shell> $ bundle exec rake test @@ -241,6 +237,16 @@ $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test. You can invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql+ also. See the file +activerecord/RUNNING_UNIT_TESTS+ for information on running more targeted database tests, or the file +ci/travis.rb+ for the test suite run by the continuous integration server. +h4. Warnings + +The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. + +As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: + +<shell> +$ RUBYOPT=-W0 bundle exec rake test +</shell> + h4. Older Versions of Ruby on Rails If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch: @@ -250,7 +256,7 @@ $ git branch --track 3-0-stable origin/3-0-stable $ git checkout 3-0-stable </shell> -TIP: You may want to "put your git branch name in your shell prompt":http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/ to make it easier to remember which version of the code you're working with. +TIP: You may want to "put your Git branch name in your shell prompt":http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/ to make it easier to remember which version of the code you're working with. h3. Helping to Resolve Existing Issues @@ -331,7 +337,7 @@ $ cd rails $ git checkout -b my_new_branch </shell> -It doesn’t matter much what name you use, because this branch will only exist on your local computer and your personal repository on Github. It won't be part of the Rails git repository. +It doesn’t matter much what name you use, because this branch will only exist on your local computer and your personal repository on Github. It won't be part of the Rails Git repository. h4. Write Your Code @@ -359,6 +365,31 @@ Rails follows a simple set of coding style conventions. The above are guidelines -- please use your best judgment in using them. +h4. Updating the CHANGELOG + +The CHANGELOG is an important part of every release. It keeps the list of changes for every Rails version. + +You should add an entry to the CHANGELOG of the framework that you modified if you're adding or removing a feature, commiting a bug fix or adding deprecation notices. Refactorings and documentation changes generally should not go to the CHANGELOG. + +A CHANGELOG entry should summarize what was changed and should end with author's name. You can use multiple lines if you need more space and you can attach code examples indented with 4 spaces. If a change is related to a specific issue, you should attach issue's number. Here is an example CHANGELOG entry: + +<plain> +* Summary of a change that briefly describes what was changed. You can use multiple + lines and wrap them at around 80 characters. Code examples are ok, too, if needed: + + class Foo + def bar + puts 'baz' + end + end + + You can continue after the code example and you can attach issue number. GH#1234 + + * Your Name * +</plain> + +Your name can be added directly after the last word if you don't provide any code examples or don't need multiple paragraphs. Otherwise, it's best to make as a new paragraph. + h4. Sanity Check You should not be the only person who looks at the code before you submit it. You know at least one other Rails developer, right? Show them what you’re doing and ask for feedback. Doing this in private before you push a patch out publicly is the “smoke test” for a patch: if you can’t convince one other developer of the beauty of your code, you’re unlikely to convince the core team either. @@ -367,7 +398,7 @@ You might want also to check out the "RailsBridge BugMash":http://wiki.railsbrid h4. Commit Your Changes -When you're happy with the code on your computer, you need to commit the changes to git: +When you're happy with the code on your computer, you need to commit the changes to Git: <shell> $ git commit -a @@ -386,7 +417,7 @@ the commit content is obvious, it may not be obvious to others. You should add such description also if it's already present in bug tracker, it should not be necessary to visit a webpage to check the history. -Description can have multiple paragraps and you can use code examples +Description can have multiple paragraphs and you can use code examples inside, just indent it with 4 spaces: class PostsController @@ -495,7 +526,7 @@ It’s entirely possible that the feedback you get will suggest changes. Don’t h4. Backporting -Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a rails team member before backporting your changes to avoid wasted effort. +Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a Rails team member before backporting your changes to avoid wasted effort. For simple fixes, the easiest way to backport your changes is to "extract a diff from your changes in master and apply them to the target branch":http://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git. @@ -520,9 +551,9 @@ $ git apply ~/my_changes.patch This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort. -Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the ruby versions listed in +.travis.yml+ before submitting your pull request. +Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the Ruby versions listed in +.travis.yml+ before submitting your pull request. -And then ... think about your next contribution! +And then... think about your next contribution! h3. Rails Contributors |