RailsBridge

h1. BugMash Cheat Sheet

Here's a list of handy shortcuts for BugMashers.

h2. Required software

If you're having trouble getting the Rails source code set up on your computer, use our [[Pre-flight Checklist]] as a guide, or drop by #railsbridge on Freenode IRC to ask for help.

h2. Generating a new Rails application

You can generate a quick sample application from the Rails 2.3.5 source code tree by 

<pre>

cd railties

rake dev

</pre>

This will create a new application named rails at the root of your Rails repository. (*NOTE*: This functionality is not available on the master branch.)

You can also generate a sample application to use by calling the rails command directly out of your source tree:

<pre>

cd /parent/of/new/app

ruby /path/to/rails/railties/bin/rails appname

cd appname/vendor

ln -s /path/to/rails/ ./rails

</pre>

This will build a new application and then symlink your checked-out rails tree into the vendor/rails folder. 

If you’re working with the master branch (Rails 3.0), you also need to bundle the necessary gems into your new application. Edit the Gemfile at the root of your new application, and add these lines at the top (*without changing what’s already there*):

<pre>

directory "vendor/rails", :glob => "{*/,}*.gemspec"

git "git://github.com/rails/arel.git"

git "git://github.com/rails/rack.git"   

</pre>

Save the file and run the bundler in the root of your new application:

<pre>

gem bundle

</pre>

Now you should be able to run @script/server@ or @script/console@ and be working with a Rails 3.0 application.

h2. Testing Rails

Just go to the folder where you’ve cloned Rails and run rake:

<pre>

cd rails

rake

</pre>

Tests not passing? Don’t panic! If you’re on the cutting-edge master branch, the problem may be the code, not you. Check http://ci.rubyonrails.org to see how the official continuous integration server for Rails is seeing things.

h2. Testing Active Record

If you wish to test patches on Active Record, you'll have to generate test databases for MySQL. Otherwise, most of the Active Record tests won't pass.  You should run these tasks in the *activerecord* directory.

<pre>

rake mysql:build_databases

</pre>

There is also a PostgreSQL task for doing the same job given you have PostgreSQL installed on your system.

<pre>

rake postgresql:build_databases

</pre>

When you're done testing patches, you can delete the generated databases.

<pre>

rake mysql:drop_databases

rake postgresql:drop_databases

</pre>

There are also useful tasks for deleting and regenerating databases if you need to refresh.

<pre>

rake mysql:rebuild_databases

rake postgresql:rebuild_databases

</pre>

If you're writing new tests for ActiveRecord, please try to reuse the existing test models instead of adding new ones.

h2. Testing specified frameworks only

Running the whole test suite takes a lot of time? You can run tests in the individual Rails frameworks also. Just cd into the library you wish to test and rake test.

<pre>

cd activesupport

rake test

</pre>

h3. Testing Active Record

Running rake test for Active Record will run tests for MySQL, SQLite3 and PostgreSQL. To run test individually based on different adapters:

<pre>

rake test_mysql

rake test_postgresql

rake test_sqlite3

</pre>

You should test all three of these widely-used database adapters if you're contributing to Active Record. See rake -T for all the adapters Rails supports, as this is only a fraction of them.

h3. Testing Individual Files

Better yet, you can test a separate file for a speed boost.

<pre>

rake test TEST=test/ordered_options_test.rb

</pre>

If testing ActiveRecord and you've changed the schema, you have to initialize the database before running the test:

<pre>

rake test_mysql TEST=test/cases/aaa_create_tables_test.rb # update the schema

rake test_mysql

TEST=test/cases/associations/has_many_through_associations_test.rb

</pre>

h2. Working with Rails and git

  Getting the Rails source:

<pre>

git clone git://github.com/rails/rails.git

cd rails

git checkout -b 2-3-stable origin/2-3-stable # this will leave you on the 2-3-stable branch

(you can also do: git checkout -t origin/2-3-stable # this will also leave you on the 2-3-stable branch)

</pre>

  Working on the master (3.0) branch:

<pre>

git checkout master

</pre>

  Working on the 2-3-stable branch:

<pre>

git checkout 2-3-stable

</pre>

  Creating your own feature branch:

<pre>

git checkout -b my_feature_branch

</pre>

  Apply a patch:

<pre>

git apply <patch file>

</pre>

  Creating a patch:

<pre>

git checkout master

git checkout -b my_feature_branch

(write and test code)

git commit -a -m "This is my great patch"

git checkout master

git pull

git checkout my_feature_branch

git rebase master

rake (to be sure tests still patch)

git format-patch master --stdout > my_great_patch.diff

</pre>

  Patching both master and 2-3-stable:

First, follow above to create a patch for master. If the same patch applies cleanly to 2-3-stable, just say so in the Lighthouse ticket and the committer will apply it to both. Otherwise, you'll need to generate a separate patch for 2-3-stable (assuming that this issue should be patched on both branches). The first thing to try is just cherry-picking your patch over to 2-3-stable:

<pre>

git checkout -b my-feature-2-3 2-3-stable

git cherry-pick <revision of change made to master>

rake test

git format-patch 2-3-stable --stdout > my_great_patch_for_rails23.diff

</pre>

As a last resort, you can write a completely separate patch for 2.3:

<pre>

git checkout 2-3-stable

git checkout -b my_feature_branch

(write and test code)

git commit -a -m "This is my great patch"

git checkout 2-3-stable

git pull

git checkout my_feature_branch

git rebase 2-3-stable

rake (to be sure tests still patch)

git format-patch 2-3-stable --stdout > my_great_patch.diff

</pre>

*NOTE*

Please keep in mind the core workflow here for Rails itself:

* All active development happens on master

* Changes targeting the stable release are made to master and flow *back* to 2.3

* Development on 2.3 with forward port to master causes log jams and is strongly discouraged

  Editing someone else's patch:

First, apply the existing patch:

<pre>

git checkout stable

git apply <patch file>

</pre>

Then if you need to make changes to the patch (perhaps because Rails has moved on), follow this advice from core:

For updating others' patches: preserving authorship is a common courtesy we encourage. The simplest is to assign authorship of the fixed commit to the original author and sign off on it. You can @git commit --author "Foo Bar <foobar@example.com>" --signoff@ to make a commit this way, or even @git commit --amend --author ... --signoff@ to change the author and add a signoff to the previous commit.

Another scenario is building on an incomplete patch. Rather than apply the patch and commit it as yourself, apply it as the original author. Then do subsequent commits as yourself. This preserves the full history and authorship.

h2. Bot commands

*!work <num> or !working <num>* - You start working on a ticket with this ID. Will return an error if ticket does not exist, or is not bugmashable.

*!stop <num> or !stopworking <num>* - You stop working on a ticket with this ID. Will return an error if you're not working on it, ticket does not exist or is not bugmashable.

*!gimme* - Tells you about a random ticket from lighthouse that nobody is (yet) working on. To start work on it, use the *!work* command.

*!review <num>* - Marks the ticket for bugmash-review in Lighthouse.

*!unreview <num>* - Removes the bugmash-review tag on the ticket in Lighthouse.

*!me* - Private messages you telling you the number of tickets you're working on and lists them off.

h2. Bugmash.com 

Some information from the [[BugMashFlowChart]] about the special strings in Lighthouse messages that Bugmash.com is looking for:

# To up or down vote a ticket use "+1" and "-1". Your comment should also include a brief explanation of your vote.

# When verifying a patch or bug use "verified" or "not reproducible".

# If you've included a patch make sure your comment includes the phrase "I've attached a patch."

# Changeset points will be awarded when the patch is committed to the Rails core.

# You can check your score at the "official scoreboard":http://bugmash.com and if we've botched your score please "let us know":http://bugmash.com/issues/new