README.md in sandboxy-1.1.1 vs README.md in sandboxy-2.0.0
- old
+ new
@@ -1,34 +1,36 @@
-# Sandboxy - virtual data-oriented environments for Rails
+# Sandboxy
-<img src="https://travis-ci.org/slooob/sandboxy.svg?branch=master" /> [](https://badge.fury.io/rb/sandboxy)
+[](https://badge.fury.io/rb/sandboxy) <img src="https://travis-ci.org/jonhue/sandboxy.svg?branch=master" />
-Sandboxy allows you to use virtual data-oriented environments inside a Rails application while being able to switch in between at runtime. It achieves that by using a combination of Rack Middleware and ActiveRecord.
+Sandboxy allows you to use virtual data-oriented environments inside a Rails application while being able to switch between them at runtime. It achieves that by using a combination of Rack Middleware and ActiveRecord.
---
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Setup](#setup)
- * [Configuration](#configuration)
- * [Sandboxed methods](#sandboxed-methods)
- * [Sandboxy methods](#sandboxy-methods)
+ * [`sandboxy` methods](#sandboxy-methods)
+ * [Sandboxy class methods](#sandboxy-class-methods)
* [Switching environments](#switching-environments)
* [Sandbox & APIs](#sandbox--apis)
+* [Configuration](#configuration)
+* [Testing](#testing)
+ * [Test Coverage](#test-coverage)
* [To Do](#to-do)
* [Contributing](#contributing)
* [Contributors](#contributors)
- * [Semantic Versioning](#semantic-versioning)
+ * [Semantic versioning](#semantic-versioning)
* [License](#license)
---
## Installation
-Sandboxy works with Rails 4.0 onwards. You can add it to your `Gemfile` with:
+Sandboxy works with Rails 5.0 onwards. You can add it to your `Gemfile` with:
```ruby
gem 'sandboxy'
```
@@ -41,31 +43,21 @@
$ gem install sandboxy
If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
```ruby
-gem 'sandboxy', github: 'slooob/sandboxy'
+gem 'sandboxy', github: 'jonhue/sandboxy'
```
Now run the generator:
$ rails g sandboxy
-You can specify your applications default environment by passing `--default live` or `--default sandbox`. Learn more about switching environments [here](#switching-environments).
-
-To set that your app should retain it's environment at runtime on new requests pass `--retain_environment true`.
-
-You can always update your [configuration](#configuration) later.
-
To wrap things up, migrate the changes into your database:
$ rails db:migrate
-**Note:** Use `rake db:migrate` instead if you run Rails < 5.
-
-This will create a configuration file under `config/sandboxy.yml` as well as a migration file and the `Sandbox` model.
-
## Usage
### Setup
Add Sandboxy to the models where you want to separate live & sandbox records:
@@ -74,29 +66,23 @@
class Foo < ApplicationRecord
sandboxy
end
```
-In most use cases you would want to add sandboxy to a lot of ActiveRecord models if not all. To simplify that you could create a new class and let all your models inherit from it:
+In most use cases you would want to add `sandboxy` to a lot of ActiveRecord models if not all. To simplify that you could create a new class and let all your models inherit from it:
```ruby
class SharedSandbox < ApplicationRecord
sandboxy
end
class Foo < SharedSandbox
end
```
-### Configuration
+### `sandboxy` methods
-In `config/sandboxy.yml` you define your app's default environment. This can be either set to `live` or `sandbox`. It defaults to `live`.
-
-Now this default gets refreshed before every new request. To retain any environment you [switched in at runtime](#switching-environments), you need to set `retain_environment` to `true`. Defaults to `false`.
-
-### Sandboxed methods
-
By default you can only access records belonging to the current environment (`live` or `sandbox`):
```ruby
$sandbox = true
Foo.all # => returns all sandbox foo's
@@ -127,26 +113,26 @@
foo.live? # => true
foo.make_sandboxed
foo.sandboxed? # => true
```
-### Sandboxy methods
+### `Sandboxy` class methods
To access your default environment setting:
```ruby
-Sandboxy.environment # => 'live' / 'sandbox'
-Sandboxy.sandbox? # => true / false
-Sandboxy.live? # => true / false
+Sandboxy.configuration.environment # => 'live' / 'sandbox'
+Sandboxy.configuration.sandbox? # => true / false
+Sandboxy.configuration.live? # => true / false
```
-**Note:** `Sandboxy.environment` does *NOT* return the apps current environment. For that use the [`$sandbox` variable](#switching-environments) instead.
+**Note:** `Sandboxy.configuration.environment` does *NOT* return the apps current environment. For that use the [`$sandbox` variable](#switching-environments) instead.
-You can also access whether your app retains your environment throughout request:
+You can also access whether your app retains your environment throughout requests:
```ruby
-Sandboxy.retain_environment # => true / false
+Sandboxy.configuration.retain_environment # => true / false
```
### Switching environments
At runtime you can always switch environments by using the `$sandbox` variable anywhere in your application. Set it to `true` to enable the `sandbox` environment. Set it to `false` to enable the `live` environment. That makes Sandboxy super flexible.
@@ -159,36 +145,80 @@
Whenever you authenticate your API's consumer, just make sure to set the `$sandbox` variable accordingly to the credential the consumer used. From thereon, Sandboxy will make sure that your consumer only reads & updates data from the environment he is in.
---
+## Configuration
+
+You can configure Sandboxy by passing a block to `configure`. This can be done in `config/initializers/sandboxy.rb`:
+
+```ruby
+Sandboxy.configure do |config|
+ config.environment = 'sandbox'
+end
+```
+
+**`environment`** Set your environment default: Must be either `live` or `sandbox`. This is the environment that your app boots with. By default it gets refreshed with every new request to your server. Defaults to `'live'`.
+
+**`retain_environment`** Specify whether to retain your current app environment on new requests. If set to `true`, your app will only load your environment default when starting. Every additional switch of your environment at runtime will then not be automatically resolved to your environment default on a new request. Takes a boolean. Defaults to `false`.
+
+---
+
+## Testing
+
+Tests are written with Shoulda on top of `Test::Unit` with Factory Girl being used instead of fixtures. Tests are run using rake.
+
+1. Fork this repository
+2. Clone your forked git locally
+3. Install dependencies
+
+ `$ bundle install`
+
+4. Run tests
+
+ `$ rake test`
+
+### Test Coverage
+
+Test coverage can be calculated using SimpleCov. Make sure you have the [simplecov gem](https://github.com/colszowka/simplecov) installed.
+
+1. Uncomment SimpleCov in the Gemfile
+2. Uncomment the relevant section in `test/test_helper.rb`
+3. Run tests
+
+ `$ rake test`
+
+---
+
## To Do
-* Leave your suggestions [here](https://github.com/slooob/sandboxy/issues/new)
+[Here](https://github.com/jonhue/sandboxy/projects/1) is the full list of current projects.
+To propose your ideas, initiate the discussion by adding a [new issue](https://github.com/jonhue/sandboxy/issues/new).
+
---
## Contributing
We hope that you will consider contributing to Sandboxy. Please read this short overview for some information about how to get started:
-[Learn more about contributing to this repository](https://github.com/slooob/sandboxy/blob/master/CONTRIBUTING.md), [Code of Conduct](https://github.com/slooob/sandboxy/blob/master/CODE_OF_CONDUCT.md)
+[Learn more about contributing to this repository](https://github.com/jonhue/sandboxy/blob/master/CONTRIBUTING.md), [Code of Conduct](https://github.com/jonhue/sandboxy/blob/master/CODE_OF_CONDUCT.md)
### Contributors
Give the people some :heart: who are working on this project. See them all at:
-https://github.com/slooob/sandboxy/graphs/contributors
+https://github.com/jonhue/sandboxy/graphs/contributors
### Semantic Versioning
Sandboxy follows Semantic Versioning 2.0 as defined at http://semver.org.
## License
MIT License
-Copyright (c) 2017 Slooob
+Copyright (c) 2017 Jonas Hübotter
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell