This is based on both research and experience.
I upgraded a Rails 3 app to Rails 3.1.
You might want to read the changelog (which is not complete) to find out what else has changed.
I encountered issues with mixins and SCSS. This is probably a known issue which they are fixing.
Encountered errors due to a class renamed. I recommend using this for now:
gem 'will_paginate', :git => 'firstname.lastname@example.org:bridgeutopia/will_paginate.git', :branch => 'rails3'
If you use cucumber, it currently doesn't work for me. But Rspec works perfectly. This is a big issue for some. I do not want to bother fixing it right now. Testing manually doesn't hurt.
Please look at this interesting post on stackoverflow. If you're like me (easily annoyed), check that out.