Contingency
"Freedom is the recognition of contingency."
- Richard M. Rorty
Contingency is the custom error page controller you've implemented in every project you've ever written. It's designed to be framework-agnostic and has many integrations to make using it as easy as calling a config block.
So why implement it yourself again?
It's quick to get started, gives you full customization over Exception coverage, gives you full control over rendering your own error page, and has a contingency plan itself in the event that your custom error views trigger an Exception.
It's also very lightweight: the core functionality (the module in contingency/plan.rb
) is less than 50 lines; and only adds 3 integration methods, 2 helper methods, and 1 controller action method to your controller. Everything but the controller method is private.
Table of Contents
- Installation
- Configuration
- Supported Integrations
- Integrating Contingency Yourself
- Versionings
- Contributing Integrations
- Contributing to Contingency
- Credits
Installation
Add this line to your application's Gemfile:
gem 'contingency-my_framework_name', '~> x.0'
...where my_framework_name
is the name of your framework, and x
is the major version of the framework you're using.
Then, execute:
$ bundle
Finally, enable Contingency in whatever object serves as your controller:
include Contingency::Plan
Configuration
Contingency-Rails uses the same configuration object as Contingency, but has different defaults. Run 'rake contingency:generate:config' to create a highly documented contingency.rb
file in the root of your project that goes over all configuration options and defaults.
Supported Integrations
Integration | Integration Quality | Supported Versions | Maintainer |
Rails | **Bad** | 3.x | christhekeele |
Great integrations have functional tests and good documentation, good integrations only have functional tests, poor integrations only have documentaion, and bad ones have neither.
Integrating it Yourself
If the framework you're using doesn't have a Contingency integration, you're only 3 methods away from integrating it yourself.
Integration API
Please Contribute
If you decide to go through this trouble, you really should consider contributing your Contingency integration to Contingency.
Versioning
Contingency Versioning
Contingency itself is versioned as it changes. It bumps its major version as its API changes, which is rarely, as its public API only requires 3 methods. It uses symantic versioning. This means you should safely be able to install it with loose bundler dependencies.
Integration Versioning
Contingency integrations should take their major version number from their frameworks. The rest is up to the maintainer.
Contributing Integrations
See contingency-rails as an example.
- Create a new gem named after your framework (
bundle gem contingency-my_integration
) - Add Contingency as a dependency to your gemspec and bundle install
- Generate an integration template (
bundle exec rake contingency:generate:plan[my_integration]
) - Implement the 3 API methods that rake instructs you to
- Commit your changes (
git commit -am 'Created my_integration'
) - Push (
git push origin master
) - Create the intital build of your gem (
gem build contingency-my_integration
) - Release your gem (
gem push contingency-my_integration.gem
) - Revel in the fact that you've provided a Contingency plan for you and yours
- Follow the steps below to update this README with links to your Contingency integration
Contributing to Contingency
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Credits
Contributers
- None, aside from the creator. Be the first!!
Shout-Outs
- Thanks to ryanb, and his subscription-worthy Railscasts, which have inspired us all. Especially us Pro users.