Sinatra 1.0 Frequently Asked Questions
Sinatra is going 1.0. Here are some things you should know:
Is Sinatra 1.0 a rewrite / major conceptual overhaul?
No. Sinatra 1.0 is very much the same codebase as the current stable 0.9 release (0.9.6). The largest changes are internal - we’re dropping the backward compatibility module and test suite that’s been maintained since the 0.3 release. The majority of obsoleted features are simple class/method name changes that have been documented for some time. Very few features have been removed in their entirety.
Some new features have been introduced.
Will my existing Sinatra app work with 1.0? How can I check?
Maybe.
If you’ve kept up with deprecations and use officially documented features, your app should be fine under Sinatra 1.0.
The latest Sinatra 0.9.x release (0.9.6 at time of writing) includes comprehensive deprecation warnings for all incompatibilities introduced in Sinatra 1.0. Run your test suite and app under 0.9.6 and watch for warnings on standard error. When no more deprecation warnings remain, upgrade your staging environment to Sinatra 1.0 and verify that stuff works.
Can I install and run under Sinatra 1.0 today?
YES! Install the latest 1.0 release with:
gem install sinatra
Alternatively, you can grab a clone of the master
branch:
git clone git://github.com/sinatra/sinatra.git
RUBYLIB="$(pwd)/sinatra/lib:$RUBYLIB"
What incompatibilities are being introduced in Sinatra 1.0?
The following is a comprehensive list of features obsoleted in the 1.0 release. All of these have been deprecated for some time:
-
The
sinatra/test
library is obsolete. This includes theSinatra::Test
module, theSinatra::TestHarness
class, and theget_it
,post_it
,put_it
,delete_it
, andhead_it
helper methods. TheRack::Test
library should be used instead. -
Test framework specific libraries (
sinatra/test/spec
,sinatra/test/bacon
,sinatra/test/rspec
, etc.) are obsolete. See Testing Sinatra for instructions on setting up a testing environment under each of these frameworks. -
Sinatra::Default
is obsolete; useSinatra::Base
instead.Sinatra::Base
acts more likeSinatra::Default
in 1.0. For example, static files and error handlers are enabled by default in all environment and classy development error pages are enabled in development environments. -
Auto-requiring template libraries in the
erb
,builder
,haml
, andsass
methods is obsolete due to thread-safety issues. You must require the template libraries explicitly in your app. -
The
:views_directory
option to rendering methods is obsolete; use:views
instead. -
The
:haml
and:sass
options to rendering methods are obsolete. Template engine options should be passed in the second Hash argument instead. -
The
media_type
helper method is obsolete. Usemime_type
instead. -
The
mime
main and class method is obsolete. Usemime_type
instead. -
The request-level
send_data
method is no longer supported. -
The
Sinatra::Event
andSinatra::EventContext
classes are no longer supported. This may effect extensions written for versions prior to 0.9.2. See Writing Sinatra Extensions for the officially supported extensions API. -
The
set_option
andset_options
methods are obsolete; useset
instead. -
The
:env
setting (settings.env
) is obsolete; use:environment
instead. -
The request level
stop
method is obsolete; usehalt
instead. -
The request level
entity_tag
method is obsolete; useetag
instead. -
The request level
headers
method (HTTP response headers) is obsolete; useresponse['Header-Name']
instead. -
Sinatra.application
is obsolete; useSinatra::Application
instead. -
Using
Sinatra.application = nil
to reset an application is obsolete. This should no longer be necessary. -
Using
Sinatra.default_options
to set base configuration items is obsolete; useSinatra::Base.set(key, value)
instead. -
The
Sinatra::ServerError
exception is obsolete. All exceptions raised within a request are now treated as internal server errors and result in a 500 response status.
What about new features?
See the CHANGES file for a list of features added in the 1.0 release. There’s also a comprehensive diff of all changes between the 0.9.x and 1.0 releases.
Lastly, the 1.0 Lighthouse milestone page includes 80 tickets with details on various features and bug fixes.
How will versions be handled in the 1.x series?
We’ve adopted the Semantic Versioning Model. All 1.x releases will be backward compatible with the initial 1.0 release.
(This is one of the reasons we’ve waited so long to do an official 1.0 release. We’re required not to break anything shipped in 1.0 for a very long time, so interfaces we don’t like require considerable scrutiny.)
Will the 0.9.x series continue to be maintained?
Yes. There will be additional Sinatra 0.9.x releases for security issues or major defects. No new features will be added to the 0.9.x series.
The 0.9.x series will be maintained for as long as people use it.
How can I pin my app to 0.9.x to avoid upgrading to 1.0?
You shouldn’t have to do anything if you bundle/vendor sinatra with your
app. Just make sure you’re pulling from the 0.9.x
branch or vendoring an
0.9.x
gem.
If you use Rubygems, there’s a very real possibility that Sinatra will be upgraded to 1.0 on your system. You can force your apps to use an 0.9.x version with:
gem 'sinatra', '< 1.0'