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?
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
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:
sinatra/testlibrary is obsolete. This includes the
Sinatra::TestHarnessclass, and the
head_ithelper methods. The
Rack::Testlibrary should be used instead.
Test framework specific libraries (
sinatra/test/rspec, etc.) are obsolete. See Testing Sinatra for instructions on setting up a testing environment under each of these frameworks.
Sinatra::Defaultis obsolete; use
Sinatra::Baseacts more like
Sinatra::Defaultin 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
sassmethods is obsolete due to thread-safety issues. You must require the template libraries explicitly in your app.
:views_directoryoption to rendering methods is obsolete; use
:sassoptions to rendering methods are obsolete. Template engine options should be passed in the second Hash argument instead.
media_typehelper method is obsolete. Use
mimemain and class method is obsolete. Use
send_datamethod is no longer supported.
Sinatra::EventContextclasses 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.
set_optionsmethods are obsolete; use
settings.env) is obsolete; use
The request level
stopmethod is obsolete; use
The request level
entity_tagmethod is obsolete; use
The request level
headersmethod (HTTP response headers) is obsolete; use
Sinatra.applicationis obsolete; use
Sinatra.application = nilto reset an application is obsolete. This should no longer be necessary.
Sinatra.default_optionsto set base configuration items is obsolete; use
Sinatra::ServerErrorexception 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?
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
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'